Knife4j 介绍
Knife4j 官网
Knife4j是一款基于Swagger生成API文档的增强工具,它简化了开发者构建和管理RESTful API文档的过程。通过自动扫描项目中的接口信息,Knife4j能够生成详细、易读的API文档,无需手动编写和维护。它提供交互式的接口调试页面,方便验证接口正确性,同时支持接口聚合和分组,便于管理大型项目中的接口。此外,Knife4j还支持Markdown文档,以及定制化配置选项,使得API文档更加美观、灵活和易于展示。总体而言,Knife4j是一款功能强大的工具,能够提升API文档质量和开发效率,推动团队协作和沟通。
依赖引入
Knife4j
其实就相当Swagger
的升级版,相比于比Swagger
要好用多了。
<!-- Knife4j -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi2-spring-boot-starter</artifactId><version>4.0.0</version>
</dependency>
Knife4j 配置类
package com.hsqyz.config.common;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.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;import java.util.ArrayList;
import java.util.List;/*** Knife4j 配置*/
@Configuration
@EnableSwagger2WebMvc // 开启Swagger
public class Knife4jConfiguration {@Bean(value = "defaultApi2")public Docket defaultApi2() {return new Docket(DocumentationType.SWAGGER_2)// 是否启用Swagger.enable(true)// 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息).apiInfo(new ApiInfoBuilder().title("API接口文档").description("API接口文档描述").termsOfServiceUrl("http://127.0.0.1:8080/")// 联系方式(这里以本人邮箱为例).contact("1926585708@qq.com").version("1.0.0").build())// 分组名称.groupName("default")// 设置哪些接口暴露给Swagger展示.select()// 这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.hsqyz.controller"))// 路径选择器.paths(PathSelectors.any()).build()/*** 设置安全模式,swagger可以设置访问token*/.securitySchemes(securitySchemes()).securityContexts(securityContexts()).pathMapping("/");}/*** 安全模式,这里指定token通过Authorization头请求头传递*/private List<SecurityScheme> securitySchemes() {List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));return apiKeyList;}/*** 安全上下文*/private List<SecurityContext> securityContexts() {List<SecurityContext> securityContexts = new ArrayList<>();securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth()).build());return securityContexts;}/*** 默认的安全上引用*/private List<SecurityReference> defaultAuth() {AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;List<SecurityReference> securityReferences = new ArrayList<>();securityReferences.add(new SecurityReference("Authorization", authorizationScopes));return securityReferences;}}
版本说明
如果出现错误:
Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
图例问题
这里提供两种修复方案
降低Spring Boot 版本到2.6.x以下版本
比如下面版本组合是兼容的
Spring Boot版本 | Swagger 版本 |
---|---|
2.5.6 | 2.9.2 |
SpringBoot版本不降级解决方案
配置文件中加上:
properties 格式
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
yaml 格式
spring: mvc:pathmatch:matching-strategy=ant_path_matcher
项目运行后,访问ip+端口号+/doc.html,比如:http://localhost:8080/doc.html
全局参数
在实际项目中访问接口都添加了权限,每次访问都要带一个请求头参数token。全局参数就是为了方便传一个固定的参数。当添加全局参数后,所有的接口都会带上该参数。
这里介绍2种设置全局参数的方法
第一种 【编码方式】
使用securitySchemes()
和securityContexts()
来设置
引用代码
/*** 安全模式,这里指定token通过Authorization头请求头传递*/private List<SecurityScheme> securitySchemes() {List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));return apiKeyList;}/*** 安全上下文*/private List<SecurityContext> securityContexts() {List<SecurityContext> securityContexts = new ArrayList<>();securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth()).build());return securityContexts;}/*** 默认的安全上引用*/private List<SecurityReference> defaultAuth() {AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;List<SecurityReference> securityReferences = new ArrayList<>();securityReferences.add(new SecurityReference("Authorization", authorizationScopes));return securityReferences;}
效果:菜单上多了一个Authorize
,在参数值中添加上信息
刷新一下,再打开接口就会发现多了个请求头部
第二种 【手动配置全局参数】
直接在菜单文档管理
→全局参数设置
,然后添加参数:
添加保存
再打开接口就会发现请求头参数加上了
过滤拦截说明
如果使用了安全相关的框架,例如(SaToken
,SpringSecurity
、包括手动定义的拦截器与过滤器),可能会拦截到Knife4j
的文档接口,导致文档加载失败,需要手动放行这方面的接口
Apifox 一键导入 knife4j 接口文档
点击导入项目
选择Knife4j
,填入地址后进行解析
解析出来的地址就是你的分组接口详细信息地址,点击提交即可
参考文章
Spring Boot项目集成Knife4j接口文档的实例代码
knife4j v2.0 用户指南