整合 Knife4j 于 Spring Cloud 网关：实现跨服务的 API 文档统一展示

🎯导读：本文档概述了构建和配置基于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 相关资源](#白名单过滤 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.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.vrs.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    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#使用

依赖

需要在网关服务添加如下依赖

<!-- 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: order
    operations-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: true
      username: admin
      password: 12344321

接下来访问接口文档就需要使用账号密码来访问了