spring boot 整合swagger2(knife4j-UI升級版
前言
Swagger 是什麼?
- Swagger 是一款RESTFUL接口的、基於YAML、JSON語言的文檔在線自動生成、代碼自動生成的工具。
1.作用:
- 啓動項目後在線自動生成API文檔
- 在線高效調試
2.官網:https://swagger.io
knife4j 是什麼?
- 爲Java MVC框架集成Swagger的增強解決方案-前身是 swagger-bootstrap-ui
- swagger-bootstrap-ui是springfox-swagger的增強UI實現,爲Java開發者在使用Swagger的時候,能擁有一份簡潔、強大的接口文檔體驗
1.作用:
- 接口排序
- 自定義文檔說明
- 訪問權限控制
- 請求參數緩存
- 調試動態請求參數
- 文檔說明等
2.官網:https://doc.xiaominfo.com
整合
一、pom.xml 引入 依賴
<!-- swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<!--防止進入swagger頁面報類型轉換錯誤,排除2.9.2中的引用,手動增加1.5.21版本-->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
<!-- swagger2-UI-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.2</version>
</dependency>
二、創建swagger配置文件(swaggerConfig.java)
@Configuration // 聲明爲配置文件,讓spring加載
@EnableSwagger2 // 支持swagger2插件配置
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config {
// apiInfo對象主要是設置我們api文檔的標題,描述,訪問的地址,創建者等信息
@SuppressWarnings("deprecation")
@Bean
public ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("濃密秀髮之謙先生的Api接口文檔")
.description("快速進行Api接口調試")
.termsOfServiceUrl("127.0.0.1:8080")
.contact("Qian")
.version("1.0")
.build();
}
/**
* 創建API
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// .pathMapping("/dev-api")
// 用來創建該API的基本信息,展示在文檔的頁面中(自定義展示的信息)
.apiInfo(apiInfo())
// 設置哪些接口暴露給Swagger展示
.select()
// 掃描所有有註解的api,用這種方式更靈活
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 掃描指定包中的swagger註解
.apis(RequestHandlerSelectors.basePackage("cn.timer.api"))
// 掃描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any()).build()
/* 設置安全模式,swagger可以設置訪問token */
.securitySchemes(securitySchemes()).securityContexts(securityContexts());
}
/**
* 安全模式,這裏指定token通過Authorization頭請求頭傳遞
*/
private List<ApiKey> securitySchemes() {
List<ApiKey> apiKeyList = new ArrayList<ApiKey>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
return apiKeyList;
}
/**
* 安全上下文
*/
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$")).build());
return securityContexts;
}
/**
* 默認的安全上引用
*/
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
}
三、啓動項目,訪問 http://localhost:8089/doc.html (請求的端口看自身情況,我項目配置的是8089)
補充:
API排序需要開啓 增強模式
若無法訪問或訪問後API無法正常顯示,原因有以下幾點:
- 路徑 http://localhost:8089/doc.html 被攔截
- 靜態資源被後端攔截,如 js、html等
效果圖
註解
-
tag排序:
@Api(tags = "1.0登錄")
@Api(tags = "2.0註冊")
-
api排序:
@ApiOperationSupport(order = 1)
@ApiOperationSupport(order = 2)
整合過程中遇到的問題:
@ApiModelProperty
註解example屬性格式無法被解析
@ApiModelProperty(value = "是否默認", example = "["0","1"]")
example 的值 [“0”,“1”] 數組格式無法被解析,建議該爲{}或字符串
感謝大家的閱讀,有收穫?希望兄弟姐妹三叔六嬸大姨大媽阿公阿婆來個三連擊,給更多的同學看到這篇文章
你的每一次回眸都是永恆,每一次鼓勵都是我前進的動力,每一次分享都是對我的認可。