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.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;
import java.util.List;/*** swagger2配置** @author huang cheng* 2021/8/13*/
@Configuration
@EnableSwagger2
public class Swagger2Config {/*引入Knife4j提供的扩展类*/private final OpenApiExtensionResolver openApiExtensionResolver;@Autowiredpublic Swagger2Config(OpenApiExtensionResolver openApiExtensionResolver) {this.openApiExtensionResolver = openApiExtensionResolver;}private final static String groupName = "cheng";//组群名称private final static String headerName = "Authorization";//需要swagger每次调接口前携带的头信息的key//private final static String headerName2 = "test";//如果要多个请求头信息，自行解放注释@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())//文档信息.groupName(groupName)//组群名称.select().apis(RequestHandlerSelectors.basePackage("com.cheng.authonlytoken.controller"))//需要扫描的api所在目录.paths(PathSelectors.any())//匹配全部地址路径.build().securitySchemes(securitySchemes())//配置安全方案.securityContexts(securityContexts())//配置安全方案所实现的上下文.extensions(openApiExtensionResolver.buildExtensions(groupName))//赋予插件体系;}private List<SecurityScheme> securitySchemes() {List<SecurityScheme> apiKeyList = new ArrayList<>();//配置header头1ApiKey token_access = new ApiKey(headerName, headerName, "header");apiKeyList.add(token_access);//配置header头2//ApiKey token_access2 = new ApiKey( headerName2, headerName2, "header");//apiKeyList.add(token_access2);return apiKeyList;}private List<SecurityContext> securityContexts() {List<SecurityContext> securityContextList = new ArrayList<>();List<SecurityReference> securityReferenceList = new ArrayList<>();//为每个api添加请求头securityReferenceList.add(new SecurityReference(headerName, scopes()));//以此类推//securityReferenceList.add(new SecurityReference(headerName2, scopes()));securityContextList.add(SecurityContext.builder().securityReferences(securityReferenceList).forPaths(PathSelectors.any()).build());return securityContextList;}private AuthorizationScope[] scopes() {return new AuthorizationScope[]{new AuthorizationScope("global", "accessAnything")};//作用域为全局}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("swagger2文档").description("更多精彩博客请关注：https://blog.csdn.net/qq_42495847?spm=1000.2115.3001.5343").termsOfServiceUrl("https://blog.csdn.net/qq_42495847?spm=1000.2115.3001.5343").contact(new Contact("cheng", "https://blog.csdn.net/qq_42495847?spm=1000.2115.3001.5343", "1003816735@qq.com")).version("1.0").build();}}

该配置实现了添加一个全局的header名为Authorization，并让所有扫描到的api携带这个header
该配置实现了自定义的文档信息（ApiInfo）

3.如果有拦截器，请放行以下地址：

    /*** 放行Swagger*/public static final String[] SWAGGER_WHITELIST = {"/swagger-ui.html/**","/swagger-ui/**","/swagger-resources/**","/v2/api-docs","/v3/api-docs","/v3/api-docs/swagger-config","/webjars/**","/doc.html",};

最后在生成环境yml配置文件中加上配置：

knife4j:# 开启增强配置 enable: true# 开启生产环境屏蔽production: true

production: true时就访问不了swagger了
测试环境改成 production: false

4.配置每个接口的swagger注解信息

swagger2常用注解：

常用注解

swagger2	swagger3	注解位置
@Api(tags = “接口类描述”)	@Tag(tags = “接口类描述”)	Controller 类上
@ApiOperation(“接口方法描述”)	@Operation(summary =“接口方法描述”)	Controller 方法上
@ApiImplicitParams	@Parameters	Controller 方法上
@ApiImplicitParam	@Parameter(description=“参数描述”)	Controller 方法上 @Parameters 里
@ApiParam(“参数描述”)	@Parameter(description=“参数描述”)	Controller 方法的参数上
@ApiIgnore	@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden	-
@ApiModel(description = “dto类描述”)	@Schema(description = “dto类描述”)	DTO类上
@ApiModelProperty(“属性描述”)	@Schema(description = “属性描述”)	DTO属性上

还是从前swagger2的味道，示例如下：

controller：

/*** 用户登录控制* @author huang cheng* 2021/8/11*/
@Api(tags = "登陆控制")
@RestController
@RequestMapping("/auth")
public class LoginController {@Resourceprivate LoginService loginService;@ApiOperation("注册")@PostMapping("/register")public CResponse<TokenVo> register(@RequestBody @Valid RegisterDto registerDto){return loginService.register(registerDto);}/*** 微信授权成功后调用该方法 获取token* @param loginDto 传入该用户可获取到的用户信息* @return token 放到Header中的Authorization作为值*/@ApiOperation("得到token")@PostMapping("/getToken")public CResponse<TokenVo> getToken(@RequestBody @Valid LoginDto loginDto){return loginService.getToken(loginDto);}/*** 得到当前token中包含的用户信息* @return 用户信息*/@ApiOperation("得到当前token中包含的用户信息")@PostMapping("/getUserInfo")public CResponse<UserInfo> getUserInfo(HttpServletRequest request){String token = request.getHeader("Authorization");if (StringUtils.isBlank(token)){throw new CommonException("token为空");}return loginService.getUserInfo(token);}
}

pojo：

/*** 登陆参数* @author huang cheng* 2021/8/11*/
@ApiModel("登陆参数")
@Data
public class LoginDto {@ApiModelProperty("登录类型")@NotBlank(message = "登录类型不能为空")private String identityType;@ApiModelProperty("标识-账号")@NotBlank(message = "账号不能为空")private String identifier;@ApiModelProperty("密码凭证")@NotBlank(message = "密码凭证不能为空")private String credential;
}

5.配置完成后访问域名/{contextPath}/doc.html

比如我访问localhost:8080/doc.html，即可进入好看的knife4j的ui界面了

6.配置统一的认证请求头

一般接口都至少戴个token来证明自己是安全的请求，通用的配置文件中已经配置了请求头Authorization，可以在Authorize界面看到

配置后点接口就可以发现请求头都带上key和value
没带上的话关闭接口页面，重新点进去

配置后api的调试界面自动带上该请求头的key和value

7.离线文档功能

在文档管理-离线文档中，可下载四种格式的接口文档：markdown、HTML、word、openapi

示例：

已经比自己写的接口文档还要好看和详细了

如果是多人合作项目，不想生成其他人的api信息，使用复制文档功能：

会复制当前api的markdown文档

4.进阶使用方法

前往官方文档查看：

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

Swagger-knife4j攻略（国产超强swagger文档）相关推荐

swagger通过swagger2markup导出PDF和HTML文档
swagger通过swagger2markup导出PDF和HTML文档本文由个人总结,如需转载使用请标明原著及原文地址写这篇文章的主要原因是,我以前写了篇spring-boot整合swagger的 ...
Swagger 自动生成 Dubbo 服务的接口文档，以及测试调用
点击上方"芋道源码",选择"设为星标" 管她前浪,还是后浪? 能浪的浪,才是好浪! 每天 8:55 更新文章,每天掉亿点点头发... 源码精品专栏原创 | J ...
windows api中文文档_Web服务开发：Spring集成Swagger，3步自动生成API文档
目录: 1,Spring Boot集成Swagger 2,Swagger接口文档页面 3,常见问题和解决方法在Sping开发REST接口服务时,API文档是不可缺少的一个重要部分.Swagger框架 ...
swagger 修改dto注解_Web服务开发：Spring集成Swagger，3步自动生成API文档
目录: 1,Spring Boot集成Swagger 2,Swagger接口文档页面 3,常见问题和解决方法在Sping开发REST接口服务时,API文档是不可缺少的一个重要部分.Swagger框架 ...
还在用 Swagger（丝袜哥）生成接口文档？我推荐你试试它。。。
作者:小鱼儿511 https://blog.csdn.net/dongbeiou/article/details/106771453 JApiDocs是一个无需额外注解.开箱即用的SpringBoo ...
jstree中文api文档_还在用 Swagger（丝袜哥）生成接口文档？我推荐你试试它。。。...
作者:小鱼儿511https://blog.csdn.net/dongbeiou/article/details/106771453JApiDocs是一个无需额外注解.开箱即用的SpringBoot接 ...
oracle中文文档_如果你还在用Swagger（丝袜哥）生成接口文档，那就真有点老“土”了！...
JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后 ...
chatGPT技巧攻略.方法大全一文读懂
这篇文章将带领你系统地掌握ChatGPT以及相关人工智能的使用方法.本文没有废话,全部都是实际操作内容,即使是完全不了解的新手也能轻松理解并开始使用.超级丰富实用的内容!全文包含1万字,作者倾尽心血! ...
Python语言学习之打印输出那些事：python输出图表和各种吊炸天的字符串或图画、版权声明(如README.md)等之详细攻略
Python语言学习之打印输出那些事:python输出图表和各种吊炸天的字符串或图画.版权声明(如README.md)等之详细攻略目录打印输出标准文档 1.输出表格 2.打印输出各种吊炸天的字符串 ...

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