knife4j-Swagger生成Api文檔的增強解決方案

目錄

介紹

引用

Api文檔的增強

開啟增強模式 yml

通路權限

接口、分組排序 

過濾請求參數

 包含請求參數

禁用調試功能

頁面路徑沖突解決

knife4j 為 Java MVC 架構生成 Api 文檔，是為Java MVC架構內建Swagger生成Api文檔的增強解決方案，,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一樣小巧,輕量,并且功能強悍! 官方參考文檔，描述很全面

介紹

更名後主要專注的方面：

• 前後端Java代碼以及前端Ui子產品進行分離,在微服務架構下使用更加靈活
• 提供專注于Swagger的增強解決方案,不同于隻是改善增強前端Ui部分

特點：

• 簡潔：基于左右菜單式的布局方式,是更符合國人的操作習慣吧.文檔更清晰...
• 個性化配置：個性化配置項,支援接口位址、接口description屬性、UI增強等個性化配置功能...
• 增強：接口排序、Swagger資源保護、導出Markdown、參數緩存衆多強大功能...

開源倉庫：

• Github

https://github.com/xiaoymin/swagger-bootstrap-ui
           

• 碼雲

https://gitee.com/xiaoym/knife4j
           

引用

不使用增強功能,純粹換一個swagger的前端皮膚，這種情況是最簡單的,你項目結構下無需變更

可以直接引用swagger-bootstrap-ui的最後一個版本1.9.6或者使用knife4j-spring-ui

老版本引用

<!--在引用時請在maven中央倉庫搜尋最新版本号-->

<dependency>    
  <groupId>com.github.xiaoymin</groupId>    
  <artifactId>swagger-bootstrap-ui</artifactId>    
  <version>1.9.6</version>
</dependency>
           

新版本引用

<dependency>    
  <groupId>com.github.xiaoymin</groupId>    
  <artifactId>knife4j-spring-ui</artifactId>    
  <version>${lastVersion}</version>
</dependency>
           

• Spring Boot項目單體架構使用增強功能

在Spring Boot單體架構下,knife4j提供了starter供開發者快速使用

<dependency>    
  <groupId>com.github.xiaoymin</groupId>    
  <artifactId>knife4j-spring-boot-starter</artifactId>    
  <version>${knife4j.version}</version>
</dependency>
           

該包會引用所有的knife4j提供的資源，包括前端Ui的jar包，2020-11更新到3.0.2

• Spring Cloud微服務架構

在Spring Cloud的微服務架構下,每個微服務其實并不需要引入前端的Ui資源,是以在每個微服務的Spring Boot項目下,引入knife4j提供的微服務starter

<dependency>    
  <groupId>com.github.xiaoymin</groupId>    
  <artifactId>knife4j-micro-spring-boot-starter</artifactId>    
  <version>${knife4j.version}</version>
</dependency>
           

在網關聚合文檔服務下,可以再把前端的ui資源引入

<dependency>    
   <groupId>com.github.xiaoymin</groupId>    
   <artifactId>knife4j-spring-boot-starter</artifactId>    
   <version>${knife4j.version}</version>
</dependency>
           

Api文檔的增強

文檔： Spring Boot 項目使用knife4j

雖然文檔都有，還是忍不住摘一些自己用到的方法 ->->

開啟增強模式 yml

在以前的版本中,開發者需要在配置檔案中手動使用

@EnableKnife4j

來使用增強，自2.0.6版本後,隻需要在配置檔案中配置

knife4j.enable=true

即可不在使用注解

knife4j:
  enable: true
           

通路權限

屏蔽所有Swagger的相關資源

knife4j:
  # 開啟增強配置 
  enable: true
　# 開啟生産環境屏蔽
  production: true
           

通路頁面權重控制-Basic認證

knife4j:
  # 開啟增強配置 
  enable: true
　# 開啟Swagger的Basic認證功能,預設是false
  basic:
      enable: true
      # Basic認證使用者名
      username: test
      # Basic認證密碼
      password: 123
           

接口、分組排序 

接口排序配置在接口上

@ApiOperationSupport(order = 33)
@ApiOperation(value = "忽略參數值-Form類型")
@PostMapping("/ex")
public Rest<LongUser> findAll(LongUser longUser) {
    Rest<LongUser> r=new Rest<>();
    r.setData(longUser);
    return r;
}
           

分組在類上

@Api(tags = "2.0.3版本-20200312")
@ApiSupport(order = 284)
@RestController
@RequestMapping("/api/nxew203")
public class Api203Constroller {
    
    
}
           

過濾請求參數

- - 直接使用實體的屬性名稱進行參數忽略

表單

@ApiOperation(value = "新增Model接口1")
@ApiOperationSupport(ignoreParameters = {"id","orderDate.id"})
@PostMapping("/insertMode1l")
public Rest<UptModel> insertModel1(UptModel uptModel){
    Rest<UptModel> r =new Rest<>();
    r.setData(uptModel);
    return r;
}
           

JSON參數

@ApiOperation(value = "新增Model接口")
@ApiOperationSupport(ignoreParameters = {"uptModel.id","uptModel.name","uptModel.orderDate.id"})
@PostMapping("/insertModel")
public Rest<UptModel> insertModel(@RequestBody UptModel uptModel){
    Rest<UptModel> r =new Rest<>();
    r.setData(uptModel);
    return r;
}
           

 包含請求參數

- - 強制包含要顯示的參數.去除多餘的參數顯示

表單

@ApiOperationSupport(order = 40,includeParameters = {"ignoreLabels","longUser.ids"})
@ApiOperation(value = "包含參數值-Form類型1")
@PostMapping("/ex1c")
public Rest<IgnoreP1> findAllc12(IgnoreP1 ignoreP1) {
    Rest<IgnoreP1> r=new Rest<>();
    r.setData(ignoreP1);
    return r;
}
           

JSON參數

@ApiOperationSupport(order = 42,includeParameters = {"ignoreP1.ignoreLabels.code","ignoreP1.longUser.ids"})
@ApiOperation(value = "包含參數值-JSON類型1")
@PostMapping("/exc3")
public Rest<IgnoreP1> findAllc3(@RequestBody IgnoreP1 ignoreP1) {
    Rest<IgnoreP1> r=new Rest<>();
    r.setData(ignoreP1);
    return r;
}
           

禁用調試功能

knife4j:
  enable: true
  setting:
    enableDebug: false
           

頁面路徑沖突解決

Springboot頁面與swagger頁面沖突解決

@Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //映射static路徑的請求到static目錄下
        // 靜态資源通路路徑和存放路徑配置
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
        // swagger通路配置
//        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/","classpath:/META-INF/resources/webjars/");
        // knife4j通路配置
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/","classpath:/META-INF/resources/webjars/");
    }
           

FAQ其他一些問題：https://doc.xiaominfo.com/faq/swagger-des-not-found.html