swagger 文檔優化 knife4j 增強 Swagger

swagger 省去了程序員開發過程中擬寫接口文檔的時間，是團隊開發必不可少的工具，原生的swagger 界面功能比較少，也不支持文檔導出，業界也有不少針對swagger 文檔界面優化的插件，良莠不齊，選一個功能比較強大的推薦一下： knife4j
官網地址：https://doc.xiaominfo.com/knife4j/documentation/

常用的增強 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 。

 

這里主要介紹 Knife4j 

• 簡介：

 

Knife4j 是為 Java MVC 框架集成 Swagger 生成 Api 文檔的增強解決方案,前身是 swagger-bootstrap-ui, 取名 knife4j 是希望它能像一把匕首一樣小巧,輕量,並且功能強悍!

 

• 兩種接口文檔訪問地址

 

   　    knife4j 訪問地址：http://localhost:8080/doc.html
　　　Swagger2.0訪問地址：http://localhost:8080/swagger-ui.html
　　　Swagger3.0訪問地址：http://localhost:8080/swagger-ui/index.html

 

• 導入依賴

<!-- Swagger 3.0.0 相關依賴 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

<!-- knife4j 3.0.2 相關依賴 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

<!-- Swagger 2.9.2 相關依賴 -->
<!--<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
 -->

 

• 編寫配置文件

//改配置文件和Swagger配置文件一致，只是添加了兩個注解
package com.example.swagger.config;  3 
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;  5 import org.springframework.context.annotation.Bean;  6 import org.springframework.context.annotation.Configuration;  7 import springfox.documentation.builders.ApiInfoBuilder;  8 import springfox.documentation.builders.PathSelectors;  9 import springfox.documentation.builders.RequestHandlerSelectors; 10 import springfox.documentation.service.ApiInfo; 11 import springfox.documentation.service.Contact; 12 import springfox.documentation.spi.DocumentationType; 13 import springfox.documentation.spring.web.plugins.Docket; 14 
@Configuration 16 //@EnableSwagger2 //開啟 Swagger2
@EnableOpenApi     //開啟 Swagger3 ，可不寫
@EnableKnife4j     //開啟 knife4j ，可不寫
public class Knife4jConfig { 20  @Bean 21     public Docket createRestApi() { 22         // Swagger 2 使用的是：DocumentationType.SWAGGER_2 23         // Swagger 3 使用的是：DocumentationType.OAS_30
        return new Docket(DocumentationType.OAS_30) 25                 // 定義是否開啟swagger，false為關閉，可以通過變量控制
                .enable(true) 27                 // 將api的元信息設置為包含在json ResourceListing響應中。
                .apiInfo(new ApiInfoBuilder() 29                         .title("Knife4j接口文檔") 30                         // 描述
                        .description("平台服務管理api") 32                         .contact(new Contact("作者", "地址", "郵箱或聯系方式))
                        .version("1.0.0") 34  .build()) 35                 // 分組名稱
                .groupName("1.0") 37                 // 選擇哪些接口作為swagger的doc發布
 .select() 39                 // 要掃描的API(Controller)基礎包
                .apis(RequestHandlerSelectors.basePackage("com.example")) 41                 // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
 .paths(PathSelectors.any()) 43  .build(); 44  } 45 }

 

• 功能特點

　　https://blog.csdn.net/qq_45632313/article/details/109777131

 

注：具體使用方式與Swagger無太大差別 

 Knife4j官文：https://doc.xiaominfo.com/knife4j/documentation/

YApi官文：https://hellosean1025.github.io/yapi/documents/index.html

參考：

https://blog.csdn.net/keep_learn/article/details/111313399

https://blog.csdn.net/a1120467800/article/details/118080195

https://blog.csdn.net/qq_45632313/article/details/109777131