Swagger 官方 Starter 配上這個增強方案是真的香！
這篇文章，簡單給大家聊聊項目必備的 Swagger 該怎么玩。
何為 Swagger ？ 簡單來說，Swagger 就是一套基於 OpenAPI 規范構建的開源工具，可以幫助我們設計、構建、記錄以及使用 Rest API。
為何要用 Swagger ? 前后端分離的情況下，一份 Rest API 文檔將會極大的提高我們的工作效率。前端小伙伴只需要對照着 Rest API 文檔就可以搞清楚一個接口需要的參數以及返回值。通過 Swagger 我們只需要少量注解即可生成一份自帶 UI 界面的 Rest API 文檔，不需要我們后端手動編寫。並且，通過 UI 界面，我們還可以直接對相應的 API 進行調試,省去了准備復雜的調用參數的過程。
這篇文章的主要內容：
- SpringBoot 項目中如何使用？
- Spring Security 項目中如何使用？
- 使用 knife4j 增強 Swagger
以下演示所用代碼，你可以在這個倉庫找到：https://github.com/Snailclimb/spring-security-jwt-guide （從零入門 ！Spring Security With JWT（含權限驗證）后端部分代碼）
SpringBoot 項目中如何使用？
Swagger3.0 官方已經有了自己的 Spring Boot Starter，只需要添加一個 jar 包即可（SpringBoot 版本 2.3.6.RELEASE）。。
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
什么都不用配置！直接在瀏覽器中訪問 :http://ip:port/swagger-ui/ 即可。
Spring Security 項目中如何使用？
如果你的項目使用了 Spring Security 做權限認證的話，你需要為 Swagger 相關 url 添加白名單。
String[] SWAGGER_WHITELIST = {
"/swagger-ui.html",
"/swagger-ui/*",
"/swagger-resources/**",
"/v2/api-docs",
"/v3/api-docs",
"/webjars/**"
};
@Override
protected void configure(HttpSecurity http) throws Exception {
http.cors().and()
// 禁用 CSRF
.csrf().disable()
.authorizeRequests()
// swagger
.antMatchers(SWAGGER_WHITELIST).permitAll()
......
}
另外，某些請求需要認證之后才可以訪問，為此，我們需要對 Swagger 做一些簡單的配置。
配置的方式非常簡單，我提供兩種不同的方式給小伙伴們。
- 登錄后自動為請求添加 token。
- 為請求的 Header 添加一個認證參數，每次請求的時候，我們需要手動輸入 token。
登錄后自動為請求添加 token
通過這種方式我們只需要授權一次即可使用所有需要授權的接口。
/**
* @author shuang.kou
* @description swagger 相關配置
*/
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("github.javaguide.springsecurityjwtguide"))
.paths(PathSelectors.any())
.build()
.securityContexts(securityContext())
.securitySchemes(securitySchemes());
}
private List<SecurityScheme> securitySchemes() {
return Collections.singletonList(new ApiKey("JWT", SecurityConstants.TOKEN_HEADER, "header"));
}
private List<SecurityContext> securityContext() {
SecurityContext securityContext = SecurityContext.builder()
.securityReferences(defaultAuth())
.build();
return Collections.singletonList(securityContext);
}
List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope
= new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Collections.singletonList(new SecurityReference("JWT", authorizationScopes));
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Security JWT Guide")
.build();
}
}
未登錄前：
登錄后：
為請求的 Header 添加一個認證參數
每次請求的時候，我們需要手動輸入 token 到指定位置。
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("github.javaguide.springsecurityjwtguide"))
.paths(PathSelectors.any())
.build()
.globalRequestParameters(authorizationParameter())
.securitySchemes(securitySchemes());
}
private List<SecurityScheme> securitySchemes() {
return Collections.singletonList(new ApiKey("JWT", SecurityConstants.TOKEN_HEADER, "header"));
}
private List<RequestParameter> authorizationParameter() {
RequestParameterBuilder tokenBuilder = new RequestParameterBuilder();
tokenBuilder
.name("Authorization")
.description("JWT")
.required(false)
.in("header")
.accepts(Collections.singleton(MediaType.APPLICATION_JSON))
.build();
return Collections.singletonList(tokenBuilder.build());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Security JWT Guide")
.build();
}
}
使用 knife4j 增強 Swagger
Swagger 原生提供的界面使用體驗比較差。常用的增強 Swagger 的方案有下面兩種：
-
YApi ：YApi 是一個可本地部署的、打通前后端及 QA 的、可視化的接口管理平台。可以幫助我們讓 swagger 頁面的體驗更加友好，目前很多大公司都在使用這個開源工具。項目地址：https://github.com/YMFE/yapi 。使用方法：當 Swagger 遇上 YApi，瞬間高大上了！
-
Knife4j ：Swagger 生成 Api 文檔的增強解決方案，前身是 swagger-bootstrap-ui 。官方文檔：https://xiaoym.gitee.io/knife4j/documentation/ 。
根據官網介紹，knife4j 是為 Java MVC 框架集成 Swagger 生成 Api 文檔的增強解決方案。
項目地址：https://gitee.com/xiaoym/knife4j 。
使用方式非常簡單,添加到相關依賴即可（SpringBoot 版本 2.3.6.RELEASE）。
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
完成之后，訪問：http://ip:port/doc.html 即可。
效果如下。可以看出，相比於 swagger 原生 ui 確實好看實用了很多。
除了 UI 上的增強之外，knife4j 還提供了一些開箱即用的功能。
比如：搜索 API 接口 （knife4j 版本>2.0.1 ）
再比如：導出離線文檔
通過 Knife4j 我們可以非常方便地導出 Swagger 文檔 ，並且支持多種格式。
- markdown：導出當前邏輯分組下所有接口的 Markdown 格式的文檔
- Html：導出當前邏輯分組下所有接口的 Html 格式的文檔
- Word:導出當前邏輯分組下所有接口的 Word 格式的文檔(自 2.0.5 版本開始)
- OpenAPI:導出當前邏輯分組下的原始 OpenAPI 的規范 json 結構(自 2.0.6 版本開始)
- PDF:未實現
以 HTML 格式導出的效果圖如下。
還等什么？快去試試吧！