Swagger-knife4j攻略（国产超强swagger文档）

swagger-knife4j测试文档完整攻略

1.swagger是什么？

swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者；

对于开发者来说，swagger是帮助后端开发人员在开发/测试环境下生成接口测试页面功能的注解；

大多数项目用的是swagger2标准OpenApi2的规范，最新的规范是swagger3的OpenApi3规范；

提到swagger，那么SpringFox和SpringDoc作为实现swagger规范的佼佼者，自然被广大后端人员大量使用，目前SpringFox已经支持swagger3的注解（swagger2也可使用），而SpringDoc已经进化成仅支持swagger3的注解了。

但是对于国人来说SpringFox和SpringDoc实现的ui界面并没有多友好，用到极致也不过是个懒得写测试用例的框架罢了，前端人员看这个ui界面可以说很抓狂，后端人员也很苦恼，我这swagger都维护好了，怎么前端就看不懂了，怎么项目经理还要我再写个接口文档？

主要原因是：英文烂、ui界面没有区分度、无法生成静态的接口文档

那么国人应该用什么框架来解决这些烦恼呢？knife4j

2.什么是knife4j？

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

简单来说，Knife4j是遵循swagger2规范，集成springFox并增强的前后端一体化框架

开源地址：https://gitee.com/xiaoym/knife4j

文档地址：https://doc.xiaominfo.com/knife4j/documentation/

截一张图展示一下：

• 把SpringFox原来的上下结构变成了左右导航栏结构，清晰
• 具有接口文档的生成功能（再也不要浪费时间再写一遍接口文档了）
• 具有前端页面添加统一Header的功能（不用在后端配置文件里写Header了）
• 每个api具备一个小型的postman功能（比SpringFox强多了）

3.通用使用教程

本教程使用的注解全部为swagger2的注解，也就是Api开头的注解，比如@ApiOperation("注册")、@Api(tags = "登陆控制")，如果已存在的项目用的是swagger3的注解，请继续使用SpringDoc哈。

仅介绍最通用的使用教程，最常用的swagger实现框架，大概就是SpringFox了，而knife4j是包含SpringFox的，需要用knife4j就要更换掉原SpringFox依赖。

1.依赖：

        <!--Swagger-->
<!--        <dependency>-->
<!--            <groupId>io.springfox</groupId>-->
<!--            <artifactId>springfox-boot-starter</artifactId>-->
<!--            <version>3.0.0</version>-->
<!--        </dependency>-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
            <version>3.0.3</version>
        </dependency>

• 已有springfox的项目注释掉再引入
• 没有springfox的项目直接引入

2.通用springboot-swagger2配置文件：

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.