一、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 註解進行描述的時候 )