本文為swagger-ui的使用配置說(shuō)明
pom的依賴：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
依賴說(shuō)明：
springfox-swagger-ui 將swagger用ui的形式展示出來(lái)，否則只能在http://ip:port/v2/api-docs路徑下展示出來(lái)
常用Swagger注解使用說(shuō)明：
@Api(tags="") -- 類上注解搁宾，用于說(shuō)明類
@ApiOperation("") -- 方法上的注解犯眠，用于說(shuō)明方法甫菠，如果不指定默認(rèn)是value值
@ApiIgnore -- 方法上使用默認(rèn)不展示被注解了的方法
@ApiModel -- 類上用于說(shuō)明對(duì)象類
@ApiModelProperty -- 對(duì)象類上的屬性描述（多用于接口參數(shù)說(shuō)明）
@ApiResponses -- 類上的注解，表示一組響應(yīng)
@ApiResponse -- 在@ApiResponses內(nèi)使用，表示一個(gè)錯(cuò)誤信息的使用eg：@ApiResponses({@ApiResponse(code=500, message = "內(nèi)部錯(cuò)誤", response = MessageReturn.class)})，其中：
- code：錯(cuò)誤碼
- message ：錯(cuò)誤信息描述
- response ：錯(cuò)誤返回信息的類型
@ApiImplicitParams -- 多用在方法上疗我，指定一組請(qǐng)求參數(shù)的各個(gè)方面
@ApiImplicitParam -- 在@ApiImplicitParams內(nèi)使用，指定一個(gè)請(qǐng)求參數(shù)的各個(gè)方面eg:@ApiImplicitParams({@ApiImplicitParam(paramType="query", name = "id", value = "主鍵ID", required = true, dataType = "Long")})
- paramType：參數(shù)放在那個(gè)地方
- header：請(qǐng)求參數(shù)的獲饶衔妗：@RequestHeader
- query：請(qǐng)求參數(shù)的獲任饪恪：@RequestParam
- path：請(qǐng)求路徑中參數(shù)的獲取：@PathVariable
- body：（不常用）
- form：（不常用）
- name：參數(shù)的名稱
- value：參數(shù)的描述
- dataType ：參數(shù)的類型
- defaultValue ：參數(shù)的默認(rèn)值
- required ：是否必填項(xiàng)
使用示例：
@Api(tags="用戶相關(guān)接口")
@RestController
@RequestMapping("/test/info")
public class InfoController {
@Autowired
public InfoService infoService;
@ApiOperation("獲取所有用戶信息", notes = "方法描述")//默認(rèn)是value
@GetMapping("/find")
public List<Info> findAll(){
return infoService.list();
}
@ApiIgnore
@ApiOperation("獲取詳細(xì)信息")
@GetMapping("/detail")
public Info detail(Long id){
return infoService.getById(id);
}
@ApiOperation("刪除詳細(xì)信息")
@DeleteMapping("/delete")
public void deleted(Long id){
this.infoService.removeById(id);
}
}
標(biāo)準(zhǔn)版：
SwaggerConfig的配置：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("測(cè)試swagger2使用")
.contact(new Contact("XXX","http://localhost","123@456"))
.version("1.0")
.build();
}
}
其中:
@Configuration ---- 告訴 Spring Boot 需要加載這個(gè)配置類
@EnableSwagger2 ---- 啟用 Swagger2
Springfox 提供了一個(gè) Docket 對(duì)象溺健，讓我們可以靈活的配置 Swagger 的各項(xiàng)屬性
通過(guò)創(chuàng)建一個(gè) ApiInfo 對(duì)象麦牺，并且使用 Docket.appInfo() 方法來(lái)設(shè)置文檔信息的描述
優(yōu)化版：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("xx.flower"))
.paths(Predicates.or(PathSelectors.ant("/test/info/find"),
PathSelectors.ant("/test/info/delete")))//接口文檔將只會(huì)展示 /test/info/find 和 /test/info/delete兩個(gè)接口。
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("測(cè)試swagger2使用")
.description("Swagger測(cè)試API描述")//加則展示鞭缭，不加不展示描述信息
.contact(new Contact("XXX","http://localhost","123@456"))
.version("1.0")
.build();
}
}
其中:
apis() ：這種方式我們可以通過(guò)指定包名的方式枕面，讓 Swagger 只去某些包下面掃描
paths() ：這種方式可以通過(guò)篩選 API 的 url 來(lái)進(jìn)行過(guò)濾
Swagger UI如下：
參考文獻(xiàn)：
https://developer.ibm.com/zh/articles/j-using-swagger-in-a-spring-boot-project/
https://www.cnblogs.com/heroinss/p/9947978.html
