三步輕松集成Swagger API文檔
本文轉載自微信公眾號「Java技術指北」，作者指北君 。轉載本文請聯系Java技術指北公眾號。
大家好， 我是指北君。
相信大家平時開發的過程中，都會使用到 API文檔工具吧?大家都在使用什么呀?Java docs，I/O Docs, apiary.io, Docco, Dexy, Doxygen, TurnAPI，Swagger。今天我就來教大家如何使用 Swagger 搭建 API 文檔，并且配置權限使用。畢竟開發文檔還是內容使用的為好，萬一上線到生產環境，沒有關swagger 又沒有設置權限，那可不GG啦。
好，我們這就上手搞起來。
我們將使用 Springfox 對 Swagger 2 規范的實現，并通過 JWT 的方式來設置權限。
配置SwaggerUI
第一步：向Spring Boot項目添加Maven依賴項
打開 pom.xml 文件，添加 springfox-boot-starter 到 maven 依賴中。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
添加 springfox-boot-starter 依賴后，spring boot 能啟動配置功能，配置好 swagger，所以我們不需要手動添加注解來啟用 Swagger。
我們啟動一下項目訪問 Swagger 文檔的 JSON API , 來看看 Springfox 是否正常運行。我們可以在瀏覽器中輸入以下URL：
http://localhost:8080/v3/api-docs
能夠看到以上的類似結果，說明我們第一步已經成功了。
第二步：將 Swagger 2 集成到 Spring Boot項目中去
我們創建一個 SwaggerConfig 類，并用 @Configuration 注解來注釋。Swagger 的配置主要圍繞著 Docket 對象來完成。我們可以在 SwaggerConfig 類中添加以下代碼。
@Configuration
public class SwaggerConfiguration {
private ApiInfo apiInfo() {
return new ApiInfo("Blog REST APIs",
"REST APIs for Blog Application",
"1.0",
"Terms of service",
new Contact("xxx", "xxx", "xxx"),
"License of API",
"API license URL",
Collections.emptyList());
}
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
在構造 Docket 對象之后，它的 select() 方法返回了 ApiSelectorBuilder 的一個實例，它提供了一種控制 Swagger 所暴露的端點的方法。
我們可以通過使用 RequestHandlerSelectors 和 PathSelectors 配置選擇 RequestHandlers 的路徑。如果兩者兩者使用 any() ， 那就說明配置所有的 API 都能在 Swagger 上顯示了。
第三步：訪問 Swagger UI
Swagger UI 是一個內置的解決方案，使用戶與Swagger 生成的API文檔的交互變得更加容易。我們在瀏覽器中輸入下面URL即可查看：
http://localhost:8080/swagger-ui/
結果應該是這樣的。
好，到這里 Swagger 的使用配置就算結束了。那接下來我們來看看怎么用JWT增加權限配置呢?
配置 JWT
JWT 是什么?相信大家都一定聽過吧，它就是 JSON Web Token 的縮寫。話不多說，直接上手代碼配置起來。在 SwaggerConfig 里面新增代碼。
我們先來配置 ApiKey 作為 JWT 的認證 header信息：
public static final String AUTHORIZATION_HEADER = "Authorization";
private ApiKey apiKey(){
return new ApiKey("JWT", AUTHORIZATION_HEADER, "header");
}
下一步，我們配置 JWT 的 SecurityContext ， 對 SecurityContext 配置全局的 AuthorizationScope :
private SecurityContext securityContext(){
return SecurityContext.builder().securityReferences(defaultAuth()).build();
}
private List<SecurityReference> defaultAuth(){
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
}
然后我們配置 Docket 對象，對 Docket 對象設置 SecurityContext ，SecuritySchemes。
@Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.securityContexts(Arrays.asList(securityContext()))
.securitySchemes(Arrays.asList(apiKey()))
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
到這里，JWT 就配置完成了，感覺是不是挺簡單的?好，我們再來運行一下，看看效果
我們點擊右上角的 Authorize 按鈕，彈出一個輸入 apiKey 的彈出層。
輸入 api key 之后，點擊 Authorize 認證通過，我們就又能調用 API 接口調試了。
用注解定制 Swagger API 文檔
為了能夠定制 Swagger 文檔，swagger-core 提供了一套注解來聲明和操作輸出。
Swagger-core 注解:
Name | Description |
@Api | 標記為 Swagger 資源 |
@ApiModel | 標記為 Swagger 模型 |
@ApiModelProperty | 模型字段的屬性說明 |
@ApiOperation | http接口的說明 |
@ApiParam | http 接口參數說明 |
更多詳細的說明可以參考 GitHub 上的解釋：https://github.com/swagger-api/swagger-core/wiki/annotations
現在我們就舉個例子來解釋怎么使用這些個注解， 首先來看 @Api 和 @ApiOperation 怎么使用：
@Api(value = "CRUD Rest APIs for Post resources")
@RestController
@RequestMapping()
public class PostController {
@ApiOperation(value = "Get All Posts REST API")
@GetMapping("/api/v1/posts")
public PostResponse getAllPosts(
@RequestParam(value = "pageNo", defaultValue = "0", required = false) int pageNo,
@RequestParam(value = "pageSize", defaultValue = "100", required = false) int pageSize
){
...
}
}
再來看看 @ApiModel 和 @ApiModelProperty 怎么使用：
@ApiModel(description = "Post model information")
@Data
public class PostDto {
@ApiModelProperty(value = "Blog post id")
private long id;
}
是不是感覺 so easy?
總結
通過這篇文章我們學習了如何通過 Springfox 來搭建 Swagger API 文檔平臺，然后也學會了如何設置 JWT 的方式做認證，保證 API 不會被別人能夠惡意使用。
