knife4j學習筆記
前言
版本說明
knife4j-spring-boot-starter=2.0.2
相關鏈接
- 官方文檔：https://doc.xiaominfo.com/guide/
- maven 地址：https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter
- github 地址：https://github.com/xiaoymin/swagger-bootstrap-ui
knife4j 簡介
https://doc.xiaominfo.com/guide/
增強註解
@ApiSort
用於Controller排序（從小到大排序）
/**
* @Author Theodore
* @Date 2020/3/3 17:48
*/
@ApiSort(1)
@Api(tags = {"用戶模塊"})
@RestController
@RequestMapping("user")
public class UserController {}
@ApiOperationSupport
用於接口排序、接口開發者、需要忽略的參數等（從小到大排序）
@GetMapping("user-str2")
@ApiOperation(value = "獲取user-str2")
@ApiOperationSupport(order = 2, author = "theodore", ignoreParameters = {"id", "role.id"})
public String getStr2(User user){
return "user-str2";
}
忽略的規則如下：
- JSON數據忽略參數：ignoreParameters = {“user.id”, “user.role.id”}
- 非JSON數據忽略參數：ignoreParameters = {“id”, “role.id”}
生產環境屏蔽接口文檔
如果使用SpringBoot框架，只需在application.properties或者application.yml配置文件中配置：
knife4j.production=true
配置此屬性後，所有資源都會屏蔽輸出。
允許開發者在配置文件中配置一個靜態的用戶名和密碼，當對接者訪問 Swagger 頁面時，輸入此配置的用戶名和密碼後才能訪問 Swagger 文檔頁面，如果您使用SpringBoot開發，則只需在相應的application.properties或者application.yml中配置如下：
## 以下配置不建議和 knife4j.production=true 一起使用，一起使用後下面配置雖然生效但是無法訪問
## 開啓Swagger的Basic認證功能,默認是false
knife4j.basic.enable=true
## Basic認證用戶名
knife4j.basic.username=zhangsan
## Basic認證密碼
knife4j.basic.password=123
實戰演練
pom 核心依賴
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j-spring-boot-starter.version}</version>
</dependency>
在 springboot 項目中添加配置
package top.simba1949.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.function.Predicate;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;
/**
* swagger-bootstrap-ui 默認訪問地址是：http://${host}:${port}/doc.html
* 注意：使用權限控制需要釋放以下三個接口：
* /swagger-resources : Swagger的分組接口
* /v2/api-docs?group=groupName : Swagger的具體分組實例接口,返回該分組下所有接口相關的Swagger信息
* /v2/api-docs-ext?group=groupName : 該接口是SwaggerBootstrapUi提供的增強接口地址,如不使用UI增強,則可以忽略該接口
*
* @Author Theodore
* @Date 2020/3/3 17:33
*/
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Conf {
/**
* springfox.documentation.spring.web.plugins.Docket 用於構建 Springfox 框架
* @return
*/
@Bean
public Docket commonDocket() {
return new Docket(DocumentationType.SWAGGER_2)
// 如果存在多個 Docket ，需要進行分組命名
.groupName("commonDocket-api")
// 設置 meta 信息
.apiInfo(apiInfo("標題：通用開發接口文檔", "描述：通用開發接口文檔"))
// 啓動 api 選擇構建器
.select()
// 哪些包路徑下屬於通用開發接口文檔
.apis(RequestHandlerSelectors.basePackage("top.simba1949.controller.common"))
// 路徑篩選 PathSelectors.any() 匹配所有接口，也可以自定義匹配哪些接口
.paths(PathSelectors.any())
// 構建
.build();
}
/**
* 自定義匹配哪些接口
* @return
*/
private Predicate<String> postPaths() {
return or(
regex("/api/posts.*"),
regex("/api/comments.*")
);
}
@Bean
public Docket companyDocket() {
return new Docket(DocumentationType.SWAGGER_2)
// 如果存在多個 Docket ，需要進行分組命名
.groupName("companyDocket-api")
// 設置 meta 信息
.apiInfo(apiInfo("標題：公司開發接口文檔", "描述：公司開發接口文檔"))
// 啓動 api 選擇構建器
.select()
// 哪些包路徑下屬於公司開發接口文檔
.apis(RequestHandlerSelectors.basePackage("top.simba1949.controller.company"))
// 路徑篩選
.paths(PathSelectors.any())
// 構建
.build();
}
private ApiInfo apiInfo(String title, String description) {
// 名稱，站點，郵箱地址
Contact contact = new Contact("simba1949", "https://simba1949.blog.csdn.net", "[email protected]");
return new ApiInfoBuilder()
// 標題
.title(title)
// 描述
.description(description)
// 服務條款鏈接
.termsOfServiceUrl("http://hantsy.blogspot.com")
// 聯繫人
.contact(contact)
// 認證許可
.license("Apache License Version 2.0")
// 認證許可鏈接
.licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")
// 版本
.version("2.0")
.build();
}
}
Controller 代碼信息
package top.simba1949.controller.common;
import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.github.xiaoymin.knife4j.annotations.ApiSort;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import top.simba1949.common.User;
/**
* @Author Theodore
* @Date 2020/3/3 17:48
*/
@ApiSort(1)
@Api(tags = {"用戶模塊"})
@RestController
@RequestMapping("user")
public class UserController {
/**
* 非JSON數據忽略參數：ignoreParameters = {"id", "role.id"}
* @param user
* @return
*/
@GetMapping("user-str1")
@ApiOperation(value = "獲取user-str1")
@ApiOperationSupport(order = 1, author = "theodore", ignoreParameters = {"id", "role.id"})
public String getStr1(User user){
return "user-str1";
}
/**
* JSON數據忽略參數：ignoreParameters = {"user.id", "user.role.id"}
* @param user
* @return
*/
@PostMapping("user-str2")
@ApiOperation(value = "獲取user-str2")
@ApiOperationSupport(order = 2, ignoreParameters = {"user.id", "user.role.id"})
public String getStr2(@RequestBody User user){
return "user-str2";
}
@GetMapping("user-str3")
@ApiOperation(value = "獲取user-str3")
@ApiOperationSupport(order = 3)
public String getStr3(){
return "user-str3";
}
@GetMapping("user-str4")
@ApiOperation(value = "獲取user-str4")
@ApiOperationSupport(order = 4)
public String getStr4(){
return "user-str4";
}
}