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>
 -->

pom依赖

• 编写配置文件

 1 //改配置文件和Swagger配置文件一致，只是添加了两个注解
 2 package com.example.swagger.config;
 3
 4 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
15 @Configuration
16 //@EnableSwagger2       //开启 Swagger2
17 @EnableOpenApi     //开启 Swagger3 ，可不写
18 @EnableKnife4j     //开启 knife4j ，可不写
19 public class Knife4jConfig {
20     @Bean
21     public Docket createRestApi() {
22         // Swagger 2 使用的是：DocumentationType.SWAGGER_2
23         // Swagger 3 使用的是：DocumentationType.OAS_30
24         return new Docket(DocumentationType.OAS_30)
25                 // 定义是否开启swagger，false为关闭，可以通过变量控制
26                 .enable(true)
27                 // 将api的元信息设置为包含在json ResourceListing响应中。
28                 .apiInfo(new ApiInfoBuilder()
29                         .title("Knife4j接口文档")
30                         // 描述
31                         .description("平台服务管理api")
32                         .contact(new Contact("作者", "地址", "邮箱或联系方式))
33                         .version("1.0.0")
34                         .build())
35                 // 分组名称
36                 .groupName("1.0")
37                 // 选择哪些接口作为swagger的doc发布
38                 .select()
39                 // 要扫描的API(Controller)基础包
40                 .apis(RequestHandlerSelectors.basePackage("com.example"))
41                 //                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
42                 .paths(PathSelectors.any())
43                 .build();
44     }
45 }

Knife4jConfig

• 功能特点

　　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