一、Swagger簡介
當下很多公司都採取前後端分離的開發模式，前端和後端的工作由不同的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文檔將會極大的提高我們的工作效率。傳統意義上的文檔都是後端開發人員手動編寫的，相信大家也都知道這種方式很難保證文檔的及時性，這種文檔久而久之也就會失去其參考意義，反而還會加大我們的溝通成本。而 Swagger 給我們提供了一個全新的維護 API 文檔的方式，下面我們就來了解一下它的優點：
1、代碼變，文檔變。只需要少量的註解，Swagger 就可以根據代碼自動生成 API 文檔，很好的保證了文檔的時效性。
2、跨語言性，支持 40 多種語言。
3、Swagger UI 呈現出來的是一份可交互式的 API 文檔，我們可以直接在文檔頁面嘗試 API 的調用，省去了準備複雜的調用參數的過程。
4、還可以將文檔規範導入相關的工具（例如 Postman、SoapUI）, 這些工具將會爲我們自動地創建自動化測試
二、項目最佳實戰
1. 引入Swagger依賴
我這裏使用starter這種簡單的方式來引入swagger
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>
</dependency>
2. 配置swagger
- 創建配置類
@Configuration
@EnableSwagger2Doc
public class SwaggerConfiguration {
@Autowired
private LXSwaggerProperties lxSwaggerProperties;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
//基本信息的配置，信息會在api文檔上顯示
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(lxSwaggerProperties.getTitle())
.version(lxSwaggerProperties.getVersion())
.build();
}
}
其中LXSwaggerProperties內容如下：
@Configuration
@ConfigurationProperties(prefix = "lx.swagger")
@Data
public class LXSwaggerProperties {
private String title = "lx接口文檔";
private String version = "1.0";
}
有了這種靈活的配置，我們就可以在配置文件中定義title和version了，當然了，我們可以根據自己的實際情況暴露需要配置的屬性。
需要注意的是，這裏面的prefix不要使用swagger，不然的話，會出現title亂碼的問題；
由於這個starter自動配置了Swagger，所以實際上已經存在了Docket，我們這種裝配方式會導致啓動失敗，錯誤如下：
***************************
APPLICATION FAILED TO START
***************************
Description:
The bean 'createRestApi', defined in class path resource [com/firewolf/lx/config/SwaggerConfiguration.class], could not be registered. A bean with that name has already been defined in class path resource [com/spring4all/swagger/SwaggerAutoConfiguration.class] and overriding is disabled.
Action:
Consider renaming one of the beans or enabling overriding by setting spring.main.allow-bean-definition-overriding=true
我們根據它的提示，在配置文件加入以下配置即可：
spring.main.allow-bean-definition-overriding=true
值得一提的是：我們可以直接通過在配置文件中加入swagger.xxx的方式來配置swagger，從而替代現在的這個類，能夠配置的屬性在SwaggerProperties類裏面。
- 在某些環境下，由於靜態資源被攔截，需要放過，建議發現有問題的時候再進行配置，如在shiro環境下：
filterChainDefinitionMap.put("/swagger-ui.html**", "anon");
filterChainDefinitionMap.put("/v2/api-docs", "anon");
filterChainDefinitionMap.put("/swagger-resources/**", "anon");
filterChainDefinitionMap.put("/webjars/**", "anon");
3. 限制暴露的接口
默認情況下，swagger會暴露所有的web類、方法、參數，這在很多時候其實不是我們想要的，我們可以通過以下幾個方法進行限定。
①. 限定包下controller生成API文檔
.apis(RequestHandlerSelectors.basePackage("com.firewolf"))
②. 限定有@Api註解的Controller生成API文檔
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
③. 限定有@ApiOperation註解的方法生成API文檔
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
④. 限定Model中的某些屬性不生成文檔
這個需要通過在屬性上面添加如下註解來實現：
@ApiModelProperty(hidden = true)
4. 效果
三、swagger註解說明
1. @Api ：請求類的說明
@Api：放在請求的類上，與 @Controller 並列，說明類的作用，如用戶模塊，訂單類等。
tags="說明該類的作用"
value="該參數沒什麼意義，所以不需要配置"
2. @ApiOperation：方法的說明
@ApiOperation："用在請求的方法上，說明方法的作用"
value="說明方法的作用"
notes="方法的備註說明"
3. @ApiImplicitParams、@ApiImplicitParam：方法參數的說明
@ApiImplicitParams：用在請求的方法上，包含一組參數說明
@ApiImplicitParam：對單個參數的說明
name：參數名
value：參數的漢字說明、解釋
required：參數是否必須傳
paramType：參數放在哪個地方
· header --> 請求參數的獲取：@RequestHeader
· query --> 請求參數的獲取：@RequestParam
· path（用於restful接口）--> 請求參數的獲取：@PathVariable
· body（請求體）--> @RequestBody User user
· form（普通表單提交）
dataType：參數類型，默認String，其它值dataType="int"
defaultValue：參數的默認值
4.@ApiResponses、@ApiResponse：方法返回值的說明
@ApiResponses：方法返回對象的說明
@ApiResponse：每個參數的說明
code：數字，例如400
message：信息，例如"請求參數沒填好"
response：拋出異常的類
5. @ApiModel：用於JavaBean上面，表示一個JavaBean
@ApiModel：用於JavaBean的類上面，表示此 JavaBean 整體的信息
（這種一般用在post創建的時候，使用 @RequestBody 這樣的場景，請求參數無法使用 @ApiImplicitParam 註解進行描述的時候 ）