Spring Boot 集成 Knife4j 的 Swagger 文档
在开发微服务应用时，API 文档的生成和维护是非常重要的一环。Swagger 是一个非常流行的 API 文档工具，可以帮助我们自动生成 RESTful API 的文档，并提供了一个友好的界面供开发者测试 API。本文将介绍如何在 Spring Boot 项目中集成 Knife4j 的 Swagger，以实现 API 文档的自动生成和展示。
官网：Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j
源码：knife4j: Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案
1. UI 界面配置步骤
1.1. 添加依赖
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.2</version>
</dependency>1.2. 添加配置文件
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {/*** 该方法的主要作用是通过knife4j生成接口文档，若想要多个分组，则需要配置多个Docket实例** @return Docket 实例，用于Swagger接口文档的配置和生成*/@Beanpublic Docket docket(Environment environment) {// 构建API信息，用于Swagger文档的元数据ApiInfo apiInfo = new ApiInfoBuilder().title("swagger测试项目接口文档") // 设置API的标题.contact(new Contact("zjp", "http://termurl.com", "zjp@email.com")).version("1.0") // 设置API的版本.description("swagger测试项目接口文档") // 设置API的描述信息.termsOfServiceUrl("http://termurl.com") // 设置服务条款URL，非必要.license("Apache 2.0") // 设置API的授权协议，非必要.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0") // 设置授权协议的URL，非必要.build();// 创建Docket实例并进行配置Docket docket = new Docket(DocumentationType.SWAGGER_2) // 指定文档类型为Swagger2。支持SWAGGER_12（1.2版本）、SWAGGER_2（2.0版本）、OAS_30（3.0版本）等。多个实例版本不同会在各个版本中各生成一个文档.enable(environment.acceptsProfiles(Profiles.of("dev", "test"))) // 设置是否启用Swagger，默认为true，也可以通过环境变量或配置文件来动态控制.apiInfo(apiInfo) // 设置API信息.select() // 进入配置选择器// 若需要匹配指定包路径的控制器，可以使用basePackage()方法，可以是包名或类名，支持通配符*；// 若需要匹配所有路径，可以使用any()方法，例如：any();// 若需要匹配指定注解的控制器，可以使用withClassAnnotation()方法，例如：withClassAnnotation(RestController.class);// 若需要匹配指定方法注解的控制器，可以使用withMethodAnnotation()方法，例如：withMethodAnnotation(ApiOperation.class);// 若不需要匹配任何注解的控制器，可以使用none()方法，例如：none();.apis(RequestHandlerSelectors.basePackage("com.zjp.knife4jswaggerdemo.controller"))// 若需要匹配指定类，可以使用any()方法，例如：any();// 若需要匹配指定路径，可以使用ant()方法，例如：ant("/api/**");// 若需要排除某些路径，可以使用ant()方法，例如：ant("!/api/**");// 若需要匹配以指定字符串结尾的路径，可以使用ant()方法，例如：ant("/**/api");// 若需要匹配以指定字符串开头的路径，可以使用regex()方法，例如：regex("/api/.*");// 若不需要匹配任何路径，可以使用none()方法，例如：none().paths(PathSelectors.any()).build() // 结束配置并构建Docket实例.groupName("default"); // 设置分组名称，多个分组名称不能重名
// .pathMapping("/") // 设置路径映射，用于指定Swagger UI的根路径，默认为/。
// .protocols(new HashSet<>(Arrays.asList("http", "https"))) // 设置支持的协议
// .securitySchemes(Collections.singletonList(new ApiKey("token", HttpHeaders.AUTHORIZATION, In.HEADER.toValue()))) // 授权信息设置，必要的header token等认证信息
// .securityContexts(Collections.singletonList(
// SecurityContext.builder()
// .securityReferences(Collections.singletonList(new SecurityReference("token", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
// .build())); // 设置全局安全上下文，用于指定全局的授权信息return docket;}/*** 该方法的主要作用是通过knife4j生成接口文档，若想要多个分组，则需要配置多个Docket实例* 例如配置第二个Docket实例，分组名称为api** @return Docket 实例，用于Swagger接口文档的配置和生成*/@Beanpublic Docket docket1() {// 构建API信息，用于Swagger文档的元数据ApiInfo apiInfo = new ApiInfoBuilder().title("swagger测试项目接口文档").version("1.0").description("swagger测试项目接口文档").build();// 创建Docket实例并进行配置Docket docket = new Docket(DocumentationType.SWAGGER_2).enable(true).apiInfo(apiInfo) // 设置API信息.select() // 进入配置选择器.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)).paths(PathSelectors.ant("/api/**")).build().groupName("api");return docket;}/*** 该方法用于在Spring MVC中配置静态资源的访问路径和位置* 它通过ResourceHandlerRegistry对象来注册资源处理器，* 从而使得特定URL路径下的请求能够映射到应用程序的静态资源上** @param registry ResourceHandlerRegistry实例，用于注册资源处理器*/protected void addResourceHandlers(ResourceHandlerRegistry registry) {// 映射/doc.html到classpath:/META-INF/resources/，以便访问该路径时能够获取到相应的静态文件registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");// 映射/webjars/**到classpath:/META-INF/resources/webjars/，用于支持webjars资源的访问registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}1.3. 启动测试
浏览器访问 http://localhost:8080/doc.html ，访问结果如下图：
界面说明：
左上角的下拉框对应的分组，如下图所示：
主页对应的是 ApiInfo 里的信息及 Docket 里的 groupName 。
在文档管理-全局参数设置可以设置全局请求头和参数。
2. 使用swagger
2.1. 常用注解
| 注解 | 用途 | 示例 |
| @Api | 标记一个控制器类，描述该类的功能 | @Api(value = "用户管理相关接口", tags = {"用户管理"}) |
| @ApiOperation | 描述一个 API 接口的方法 | @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息") |
| @ApiParam | 描述方法参数 | @ApiParam(name = "id", value = "用户ID", required = true) |
| @ApiImplicitParam | 描述隐式参数，常用于 GET 请求的查询参数 | @ApiImplicitParam(name = "token", value = "访问令牌", required = true, dataType = "string", paramType = "header") |
| @ApiImplicitParams | 描述多个隐式参数 | @ApiImplicitParams({ @ApiImplicitParam(name = "token", value = "访问令牌", required = true, dataType = "string", paramType = "header"), @ApiImplicitParam(name = "page", value = "页码", required = false, dataType = "integer", paramType = "query") }) |
| @ApiResponse | 描述方法的响应信息 | @ApiResponse(code = 200, message = "成功返回用户信息") |
| @ApiResponses | 描述多个响应信息 | @ApiResponses({ @ApiResponse(code = 200, message = "成功返回用户信息"), @ApiResponse(code = 404, message = "用户不存在") }) |
| @ApiModel | 描述一个模型类 | @ApiModel(description = "用户信息") |
| @ApiModelProperty | 描述模型类的属性 | @ApiModelProperty("主键值") |
| @ApiIgnore | 忽略某个方法或类，不生成 API 文档 | @ApiIgnore |
| @ApiExample | 描述 API 示例请求 | @ApiExample(value = "获取用户信息示例", source = "GET /users/{id}") |
2.2. 使用示例
controller层使用示例：
import com.zjp.knife4jswaggerdemo.pojo.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;@RestController
@Api(value = "用户管理相关接口", tags = {"用户管理"})
public class UserController {@GetMapping("/getUser")@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")@ApiImplicitParams({@ApiImplicitParam(name = "token", value = "访问令牌", required = true, dataType = "string", paramType = "header"),@ApiImplicitParam(name = "page", value = "页码", required = false, dataType = "integer", paramType = "query")})@ApiResponses({@ApiResponse(code = 200, message = "成功返回用户信息"),@ApiResponse(code = 404, message = "用户不存在")})public User getUser(@ApiParam(name = "id", value = "用户ID", required = true) @RequestParam Integer id) {User user = new User();user.setId(1);user.setName("Alice");user.setAge(18);user.setSex("female");return user;}
}实体类使用示例：
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
@ApiModel(value = "用户信息", description = "用户信息实体类")
public class User {@ApiModelProperty(value = "主键值", example = "1001")private Integer id;@ApiModelProperty(value = "名称", example = "Bob")private String name;@ApiModelProperty(value = "年龄", example = "32")private Integer age;@ApiModelProperty(value = "性别", example = "male")private String sex;
}2.3. 启动测试
浏览器访问 http://localhost:8080/doc.html ，访问结果如下图：
实体类信息如下（不调用实体类这里不会展示实体类信息）：
接口文档：
测试接口：
3. 其他配置
| 属性 | 默认值 | 说明值 |
|---|---|---|
knife4j.enable | false | 是否开启Knife4j增强模式 |
knife4j.cors | false | 是否开启一个默认的跨域配置,该功能配合自定义Host使用 |
knife4j.production | false | 是否开启生产环境保护策略,详情参考文档 |
knife4j.basic | 对Knife4j提供的资源提供BasicHttp校验,保护文档 | |
knife4j.basic.enable | false | 关闭BasicHttp功能 |
knife4j.basic.username | basic用户名 | |
knife4j.basic.password | basic密码 | |
knife4j.documents | 自定义文档集合，该属性是数组 | |
knife4j.documents.group | 所属分组 | |
knife4j.documents.name | 类似于接口中的tag,对于自定义文档的分组 | |
knife4j.documents.locations | markdown文件路径,可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md) | |
knife4j.setting | 前端Ui的个性化配置属性 | |
knife4j.setting.enable-after-script | true | 调试Tab是否显示AfterScript功能,默认开启 |
knife4j.setting.language | zh-CN | Ui默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US) |
knife4j.setting.enable-swagger-models | true | 是否显示界面中SwaggerModel功能 |
knife4j.setting.swagger-model-name | Swagger Models | 重命名SwaggerModel名称,默认 |
knife4j.setting.enable-document-manage | true | 是否显示界面中"文档管理"功能 |
knife4j.setting.enable-reload-cache-parameter | false | 是否在每个Debug调试栏后显示刷新变量按钮,默认不显示 |
knife4j.setting.enable-version | false | 是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点 |
knife4j.setting.enable-request-cache | true | 是否开启请求参数缓存 |
knife4j.setting.enable-filter-multipart-apis | false | 针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址 |
knife4j.setting.enable-filter-multipart-api-method-type | POST | 具体接口的过滤类型 |
knife4j.setting.enable-host | false | 是否启用Host |
knife4j.setting.enable-host-text | false | HOST地址 |
knife4j.setting.enable-home-custom | false | 是否开启自定义主页内容 |
knife4j.setting.home-custom-path | 主页内容Markdown文件路径 | |
knife4j.setting.enable-search | false | 是否禁用Ui界面中的搜索框 |
knife4j.setting.enable-footer | true | 是否显示Footer |
knife4j.setting.enable-footer-custom | false | 是否开启自定义Footer |
knife4j.setting.footer-custom-content | false | 自定义Footer内容 |
knife4j.setting.enable-dynamic-parameter | false | 是否开启动态参数调试功能 |
knife4j.setting.enable-debug | true | 启用调试 |
knife4j.setting.enable-open-api | true | 显示OpenAPI规范 |
knife4j.setting.enable-group | true | 显示服务分组 |
3.1. 访问权限控制
对应官网原文：3.5 访问权限控制 | Knife4j
3.1.1. 生产环境禁用
目前Springfox-Swagger以及Knife4j提供的资源接口包括如下：
| 资源 | 说明 |
|---|---|
| /doc.html | Knife4j提供的文档访问地址 |
| /v2/api-docs-ext | Knife4j提供的增强接口地址,自2.0.6版本后删除 |
| /swagger-resources | Springfox-Swagger提供的分组接口 |
| /v2/api-docs | Springfox-Swagger提供的分组实例详情接口 |
| /swagger-ui.html | Springfox-Swagger提供的文档访问地址 |
| /swagger-resources/configuration/ui | Springfox-Swagger提供 |
| /swagger-resources/configuration/security | Springfox-Swagger提供 |
springdoc以及Knife4j提供的资源接口包括如下：
| 资源 | 说明 |
|---|---|
| /doc.html | Knife4j提供的文档访问地址 |
| /v3/api-docs | springdoc提供的实例接口 |
| /v3/api-docs/swagger-config | springdoc提供的分组接口 |
| /v3/api-docs/** | 分组 |
| /swagger-ui/index.html | springdoc提供的文档访问地址 |
当我们部署系统到生产系统,为了接口安全,需要屏蔽所有Swagger的相关资源
如果使用SpringBoot框架,只需在application.properties或者application.yml配置文件中配置：
knife4j:# 开启增强配置 enable: true# 开启生产环境屏蔽production: true配置此属性后,所有资源都会屏蔽输出.
效果图如下：
3.1.2. 登录认证
不管是官方的swagger-ui.html或者doc.html,目前接口访问都是无需权限即可访问接口文档的,很多朋友以前问我能不能提供一个登陆界面的功能,开发者输入用户名和密码来控制界面的访问,只有知道用户名和密码的人才能访问此文档
做登录页控制需要有用户的概念,所以相当长一段时间都没有提供此功能
针对Swagger的资源接口,Knife4j提供了简单的Basic认证功能
效果图如下：
允许开发者在配置文件中配置一个静态的用户名和密码,当对接者访问Swagger页面时,输入此配置的用户名和密码后才能访问Swagger文档页面,如果您使用SpringBoot开发,则只需在相应的application.properties或者application.yml中配置如下：
knife4j:# 开启增强配置 enable: true# 开启Swagger的Basic认证功能,默认是falsebasic:enable: true# Basic认证用户名username: test# Basic认证密码password: 123如果用户开启了basic认证功能,但是并未配置用户名及密码,Knife4j提供了默认的用户名和密码：
admin/1233213.2. 请求参数缓存
在默认情况下,在接口调试的情况下,Knifetj对于接口的请求参数都会缓存起来，该配置可以在前端界面中的个性化设置中看到,如下图：
缓存的情况只会在后端没有给属性example的情况下产生,如果后端在写Swagger的注解的时候,给每个字段赋予了example的值,那么,Knife4j不会使用调试时缓存的值,而是会一直使用后端的example值。
当然，开发者也可以在后端控制文档的接口调试功能，针对请求后的参数是否需要缓存(自2.0.6版本开始)
yml配置如下：
knife4j:enable: truesetting:# 对于调试中的请求参数是否缓存进行开启配置，该参数默认为trueenable-request-cache: true也可以手动清理缓存：
3.3. 动态请求参数
方式一：后台开启
开发者也可以通过开启Knife4j的增强配置，进行默认开启，配置如下：
knife4j:enable: truesetting:# 开启动态请求参数，true-开启，false-关闭enable-dynamic-parameter: true方式二：界面开启
当在配置中勾选该选项后,我们的接口栏会有变化,如下图：
在原本已存在的参数栏下会出现一栏空的参数栏,开发者可以输入参数名称、参数值对参数进行添加
不管是参数名称的变化还是参数值的变化,变化后会自动追加一行新的调试栏参数,效果图如下：
