🎯导读：本文档概述了构建和配置基于JDK 17、Spring Boot 3.0.7及Spring Cloud 2022.0.3的微服务系统，特别聚焦于集成Knife4j以增强API文档管理和接口测试功能。文中详细介绍了如何在Spring Boot应用中添加Knife4j依赖、配置Swagger UI路径和API分组，以及使用注解为接口添加描述信息。此外，文档还讲解了通过Spring Cloud Gateway聚合多个微服务的API文档的方法，并说明了如何设置白名单和基本认证来保护API文档访问。这些步骤旨在提升开发效率，确保API文档的准确性和易用性。
文章目录
- 实践版本
- Knife4j
- 其他微服务引入Knife4j
- 依赖
- 配置文件
- 添加接口描述
- 访问接口文档
- 屏蔽请求参数字段
- 通过网关服务统一聚合访问
- 依赖
- 配置文件
- 白名单过滤 Knife4j 相关资源
- 用户名密码控制接口文档访问
实践版本
- JDK 17
- SpringBoot 3.0.7
- SpringCloud 2022.0.3
- SpringCloudAlibaba 2022.0.0.0-RC2
Knife4j
https://doc.xiaominfo.com/
其他微服务引入Knife4j
参考文档：https://doc.xiaominfo.com/docs/quick-start#spring-boot-3
我这里以admin服务为例子
依赖
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version>
</dependency>
配置文件
注意需要修改接口的扫包路径，即packages-to-scan
# springdoc-openapi项目配置
springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docsgroup-configs:- group: 'default'paths-to-match: '/**'packages-to-scan: com.vrs.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:enable: truesetting:language: zh_cn
添加接口描述
@Tag：添加类描述@Operation：添加接口描述
@RestController
@RequestMapping("/user/")
@RequiredArgsConstructor
@Tag(name = "用户管理")
public class UserController {private final UserService userService;/*** 查询用户名是否存在*/@Operation(summary = "查询用户名是否存在")@GetMapping("/v1/has-username")public Result<Boolean> hasUsername(@RequestParam("username") String username) {return Results.success(userService.hasUsername(username));}}
访问接口文档
http://ip地址:端口/doc.html，如果设置了服务访问前缀，记得要加到/doc前面，例如的地址为http://localhost:7050/admin/doc.html
屏蔽请求参数字段
有时候接口接收的参数是一个json数据，但是其中一些字段是不需要的，例如id、createTime、updateTime、isDeleted，可以通过@Schema字段将其隐藏
@Schema(description = "id", hidden = true)
private Long id;
通过网关服务统一聚合访问
参考文档：https://doc.xiaominfo.com/docs/middleware-sources/spring-cloud-gateway/spring-gateway-introduction#%E4%BD%BF%E7%94%A8
依赖
需要在网关服务添加如下依赖
<!-- Knife4j API 小刀注解依赖 -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-gateway-spring-boot-starter</artifactId><version>4.4.0</version>
</dependency>
配置文件
需要在网关服务的配置文件中的routes中设置每个微服务的接口访问地址，注意enabled一定要设置为true，才能开启聚合功能，注意如果微服务有设置接口前缀，一定要设置context-path
# knife4j的网关聚合配置 文档地址：http://{gateway.host}:{gateway.port}/doc.html
knife4j:# 聚合swagger文档gateway:# 是否开启Knife4j网关聚合功能(生产环境不建议开启)enabled: true# 排序规则(tag/operation排序自4.2.0版本新增)# 取值：alpha-默认排序规则，官方swagger-ui默认实现,order-Knife4j提供的增强排序规则，开发者可扩展x-order，根据数值来自定义排序tags-sorter: orderoperations-sorter: order# 指定聚合的策略(默认手动配置(manual)，服务发现(discover))strategy: manual# 个性化定制的部分子服务分组情况routes:- name: admin模块# 服务名service-name: vrs-admin# 真实子服务访问url地址-提供OpenAPI的文档url: /admin/v3/api-docs?group=default# 路由前缀，兼容OpenAPI3规范在聚合时丢失contextPath属性的异常情况，由开发者自己配置contextPath,Knife4j的前端Ui做兼容处理,与url属性独立不冲突，仅OpenAPI3规范聚合需要，OpenAPI2规范不需要设置此属性,默认为(apiPathPrefix)context-path: /admin# 排序order: 1
白名单过滤 Knife4j 相关资源
通过http://网关服务ip:端口/doc.html访问，发现文档请求异常
通过查看网页请求的错误，发现是权限验证的问题
那只需要在网关层放开相应资源的权限控制即可，参考文档：https://doc.xiaominfo.com/docs/features/accessControl
将相应资源地址放到白名单中
再次访问文档url，发现其他服务的接口被聚合进来了。具体原理就是网关服务通过/admin/v3/api-docs去admin服务请求了接口数据，请求到之后将其放到当前接口文档中
用户名密码控制接口文档访问
参考文档：https://doc.xiaominfo.com/docs/features/accessControl
在网关服务的配置文件中添加如下配置
knife4j:gateway:basic:enable: trueusername: adminpassword: 12344321
接下来访问接口文档就需要使用账号密码来访问了
 跟 @pytest.fixture有区别吗？)
