> 有很多人不清楚我們的swagger ui的路徑，由于我們使用了更為好用的`swagger-bootstrap-ui`，實際上使 域名+端口 +/doc.html，如：http://localhost:8086/doc.html 在沒有Swagger之前，我們需要自己手寫文檔，手寫文檔的出現問題： 1. 文檔更新時需要要與前端人員進行對接，文檔存在更新不及時 2. 接口文檔多，沒有進行分組管理，增加管理難度 3. 不能直接在線接口調試，通常需要借助工具（如postman）,效率大大降低 4. 接口說明與返回結果不明確 而通過swagger就能輕松解決這些問題，而且`spirngboot`整合swagger也相對簡單 [swagger官網](https://swagger.io/) ## 添加依賴 ``` <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>1.9.3</version> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>2.9.2</version> </dependency> ``` ## 添加配置類并開啟 在**yami-shop-api**工程中的**config**文件下，有swagger相應的配置類，只要了解具體能配置哪些東西就好了，畢竟這個東西配置一次之后就不用再動了 ```java @Configuration @EnableSwagger2 public class SwaggerConfiguration { @Bean public Docket baseRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("基礎版") .select() .apis(RequestHandlerSelectors.basePackage("com.yami.shop.api")) .paths(PathSelectors.any()) .build(); } @Bean public ApiInfo apiInfo() { return new ApiInfoBuilder() .title("亞米商城接口文檔") .description("亞米商城接口文檔Swagger版") .termsOfServiceUrl("http://www.gz-yami.com/") .contact(new Contact("廣州亞米信息科技有限公司","https://www.gz-yami.com/", "")) .version("1.0") .build(); } } ``` 特別要注意的是里面配置了api文件也就是controller包的路徑，不然生成的文檔掃描不到接口 ```java apis(RequestHandlerSelectors.basePackage("com.yami.shop.api")) ``` 用`@Configuration`注解該類，讓spring托管這個類，`@Bean`標注方法等價于XML中配置bean 用`@EnableSwagger2`標識要開啟`Swagger2` ## 接口使用 在配置好之后，我們就可以對swagger進行使用,比如在`AreaController`類中 ```java @RestController @RequestMapping("/p/area") @Api(tags="省市區接口") public class AreaController { @Autowired private AreaService areaService; @GetMapping("/listByPid") @ApiOperation(value="獲取省市區信息", notes="根據省市區的pid獲取地址信息") @ApiImplicitParam(name = "pid", value = "省市區的pid(pid為0獲取所有省份)", required = true, dataType = "String") public ResponseEntity<List<Area>> listByPid(Long pid){ List<Area> list = areaService.listByPid(pid); return ResponseEntity.ok(list); } } ``` `@Api(tags="省市區接口")`定義標簽分組接口，在這個類下定義的所有接口將位于這個標簽之下 `@ApiOperation()`定義具體的接口標題信息，notes可以為這個標簽添加注釋 `@ApiImplicitParam()`對應的參數列表信息，用戶告訴前端開發人員，這個接口需要傳遞什么參數及參數的說明 如有多個參數需要說明，可使用`@ApiImplicitParams()`下面可包含多個`@ApiImplicitParam()` ## 實體類 ```java @Data @TableName("tz_area") public class Area implements Serializable { private static final long serialVersionUID = -6013320537436191451L; @TableId @ApiModelProperty(value = "地區id",required=true) private Long areaId; @ApiModelProperty(value = "地區名稱",required=true) private String areaName; @ApiModelProperty(value = "地區上級id",required=true) private Long parentId; @ApiModelProperty(value = "地區層級",required=true) private Integer level; @TableField(exist=false) private List<Area> areas; } ``` `@ApiModelProperty()`利用這個注解可以告訴前端開發人員該字段代表的含義 ## 常用注解 | 注解 | 作用 | | ------------------ | ------------------------------------ | | @Api | 修飾整個類，描述Controller的作用 | | @ApiOperation | 描述一個類的一個方法，或者說一個接口 | | @ApiParam | 單個參數描述 | | @ApiModel | 用對象來接收參數 | | @ApiProperty | 用對象接收參數時，描述對象的一個字段 | | @ApiResponse | HTTP響應其中1個描述 | | @ApiResponses | HTTP響應整體描述 | | @ApiIgnore | 使用該注解忽略這個API | | @ApiError | 發生錯誤返回的信息 | | @ApiImplicitParam | 一個請求參數 | | @ApiImplicitParams | 多個請求參數 | ## 分頁參數的文檔以及關于swagger文檔的騷操作 我們仔細留意swagger文檔，可以發現 swagger文檔返回接口數據的url為：`/v2/api-docs` 。這個url被 `springfox.documentation.swagger2.web.Swagger2Controlle#getDocumentation()` 關聯。通過`jsonSerializer.toJson(swagger)` 生成特定的json文檔。 當我們使用`PageParam<T>` 這個分頁參數生成文檔的時候，總是會返回泛型里面的對象信息，我們根據無論使用`@ApiParam(hidden = true)` 又或者是 `@JsonIgnore` 都無效，所以我們可以修改自己的`jsonSerializer`生成的響應的json 自定義Swagger 的序列化，去除分頁參數中的records值 ```java public class SpringfoxJsonSerializer extends JsonSerializer { public SpringfoxJsonSerializer(List<JacksonModuleRegistrar> modules) { super(modules); } @Override public Json toJson(Object toSerialize) { if (!(toSerialize instanceof Swagger)) { return super.toJson(toSerialize); } Swagger swagger = (Swagger)toSerialize; swagger.getPaths().forEach((key, path) ->{ Operation get = path.getGet(); if (get != null) { List<Parameter> parameters = get.getParameters(); if (parameters != null) { parameters.removeIf(parameter -> parameter.getName().startsWith("records[0].")); } } }); return super.toJson(swagger); } } ``` 新序列化的bean ```java @Configuration public class SpringFoxJsonSerializerConfig { @Bean @Primary public JsonSerializer yamiSpringfoxJsonSerializer(List<JacksonModuleRegistrar> moduleRegistrars) { return new SpringfoxJsonSerializer(moduleRegistrars); } } ```