整合 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文档的准确性和易用性。

文章目录

实践版本

  • 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服务为例子

依赖

xml 复制代码
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

配置文件

注意需要修改接口的扫包路径,即packages-to-scan

yaml 复制代码
# 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:添加接口描述
java 复制代码
@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数据,但是其中一些字段是不需要的,例如idcreateTimeupdateTimeisDeleted,可以通过@Schema字段将其隐藏

java 复制代码
@Schema(description = "id", hidden = true)
private Long id;

通过网关服务统一聚合访问

参考文档:https://doc.xiaominfo.com/docs/middleware-sources/spring-cloud-gateway/spring-gateway-introduction#使用

依赖

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

xml 复制代码
<!-- 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

yaml 复制代码
# 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

在网关服务的配置文件中添加如下配置

yaml 复制代码
knife4j:
  gateway:
    basic:
      enable: true
      username: admin
      password: 12344321

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

相关推荐
iuyou️6 分钟前
Spring Boot知识点详解
java·spring boot·后端
一弓虽18 分钟前
SpringBoot 学习
java·spring boot·后端·学习
ai大佬25 分钟前
Java 开发玩转 MCP:从 Claude 自动化到 Spring AI Alibaba 生态整合
java·spring·自动化·api中转·apikey
姑苏洛言26 分钟前
扫码小程序实现仓库进销存管理中遇到的问题 setStorageSync 存储大小限制错误解决方案
前端·后端
光而不耀@lgy41 分钟前
C++初登门槛
linux·开发语言·网络·c++·后端
方圆想当图灵1 小时前
由 Mybatis 源码畅谈软件设计(七):SQL “染色” 拦截器实战
后端·mybatis·代码规范
毅航1 小时前
MyBatis 事务管理:一文掌握Mybatis事务管理核心逻辑
java·后端·mybatis
我的golang之路果然有问题2 小时前
速成GO访问sql,个人笔记
经验分享·笔记·后端·sql·golang·go·database
柏油2 小时前
MySql InnoDB 事务实现之 undo log 日志
数据库·后端·mysql
来自星星的猫教授2 小时前
spring,spring boot, spring cloud三者区别
spring boot·spring·spring cloud