Spring Cloud Gateway + Knife4j 4.3 实现微服务网关聚合接口文档

有来技术2023-10-29 14:09

目录

前言

youlai-mall 开源微服务商城新版本基于 Spring Boot 3 和 Java 17，同时采用 Knife4j 4.3。与以前版本不同的是，新版本的 Knife4j 不再依赖 Springfox 框架（该框架于2020年停止更新）作为基础的 OpenAPI3 规范，而选择了 SpringDoc 作为底层依赖框架的 OpenAPI3 规范的实现。因此，相对于以前的版本，新版本存在较大的差异。

在新版本中，您可以参考 Knife4j 官网 进行适配和升级。本文将介绍新版本中 Knife4j 4.3 和微服务的整合、 Spring Cloud Gateway 网关聚合，以及如何自动填充 Spring Authorization Server 的自定义扩展的 OAuth2 密码模式的 access_token。

Spring Cloud 整合 Knife4j

这里的 Spring Cloud 微服务是除了网关(youlai-gateway)之外的其他服务，像系统服务(youlai-system)和商城服务(mall-*)

pom.xml

添加 knife4j 的 maven 依赖，参考 Spring Boot 3 整合 Knife4j

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

application.yml

除了 packages-to-scan 扫描接口包路径，其他默认即可，参考 Spring Boot 3 整合 Knife4j

yaml 复制代码 
spring:
  security:
    oauth2:
      authorizationserver:
      	# OAuth2 认证路径
        token-uri: http://localhost:9999/youlai-auth/oauth2/token
        
# 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: 
      	# 配置接口文档扫描包路径，每个服务的路径不同，下面是系统服务(youlai-system)的包路径
        - com.youlai.system.controller
      
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: false
  setting:
    language: zh_cn

SwaggerConfig.java

java 复制代码 
package com.youlai.system.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.OAuthFlow;
import io.swagger.v3.oas.models.security.OAuthFlows;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;

/**
 * Swagger 配置类
 * <p>
 * 基于 OpenAPI 3.0 规范 + SpringDoc 实现 + knife4j 增强
 *
 * @author haoxr
 * @since 3.0.0
 */
@Configuration
public class SwaggerConfig {

    /**
     * OAuth2 认证 endpoint
     */
    @Value("${spring.security.oauth2.authorizationserver.token-uri}")
    private String tokenUrl;

    /**
     * OpenAPI 配置（元信息、安全协议）
     */
    @Bean
    public OpenAPI apiInfo() {
        return new OpenAPI()
                .components(new Components()
                        .addSecuritySchemes(HttpHeaders.AUTHORIZATION,
                                new SecurityScheme()
                                        // OAuth2 授权模式
                                        .type(SecurityScheme.Type.OAUTH2)
                                        .name(HttpHeaders.AUTHORIZATION)
                                        .flows(new OAuthFlows()
                                                .password(
                                                        new OAuthFlow()
                                                                .tokenUrl(tokenUrl)
                                                                .refreshUrl(tokenUrl)
                                                )
                                        )
                                        // 安全模式使用Bearer令牌（即JWT）
                                        .in(SecurityScheme.In.HEADER)
                                        .scheme("Bearer")
                                        .bearerFormat("JWT")
                        )
                )
                // 接口全局添加 Authorization 参数
                .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION))
                // 接口信息定义
                .info(new Info()
                        .title("系统服务")
                        .version("3.0.0")
                        .description("用户、角色、菜单、部门、字典等接口")
                        .license(new License().name("Apache 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0"))
                );
    }


}

访问单服务接口文档

访问 Knife4j 的文档地址：http://ip:port/doc.html即可查看文档

系统服务 (youlai-system) 的接口文档地址 http://localhost:8800/doc.html ，访问页面如下：

Spring Cloud Gateway 网关聚合

参考 Knife4j 官方文档：Spring Cloud Gateway 网关聚合

Knife4j 官方提供 手动配置 和 服务发现 两种聚合方式，如果微服务数量少且有定制化文档需求建议 手动配置，否则一般还是推荐服务发现的方式，可以避免每次新增一个服务还得手动去添加配置的烦恼。

这里使用的是 服务发现 聚合方式，如果手动请参考官方配置（很详细）

pom.xml

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

application.yml

yaml 复制代码 
spring:
  cloud:
    gateway:
      discovery:
        locator:
          # 启用服务发现
          enabled: true
          lower-case-service-id: true
      # 网关路由
      routes:
        - id: 系统服务
          uri: lb://youlai-system
          predicates:
            - Path=/youlai-system/**
          filters:
            - StripPrefix=1 

# knife4j 网关聚合
knife4j:
  gateway:
    enabled: true
    # 指定服务发现的模式聚合微服务文档，并且是默认 default 分组
    strategy: discover
    discover:
      # OpenAPI 3.0 规范 
      version: openapi3
      enabled: true

访问网关聚合接口文档

访问 Knife4j 的文档地址：http://ip:port/doc.html即可查看文档

网关(youlai-gateway) 的接口文档地址 http://localhost:9999/doc.html ，访问页面如下图：

接口测试

接下来做一个 OAuth2 登录认证（Spring Authorization Server 扩展的 OAuth2 密码模式），认证成功拿到访问令牌(access_token) 去请求获取登录用户信息接口测试 。

认证成功之后，再去打开其他接口会请求头会自动携带访问令牌。

登录认证

点击接口文档左侧菜单栏 Authorize 打开认证页面，填写图示 OAuth2 密码模式授权认证参数

💡 特别提醒: Knife4j 自动填充请求头前提需要数据原生返回，那么什么是原生数据格式？

  • ✔️原生数据格式

    json 复制代码 
    {
    "access_token": "eyJraWQiOiJlNTg1NTQ3MS02ZDlmLTRkOWEtODJlNi1mN2QyNjY4YjhhZDgiLCJhbGciOiJSUzI1NiJ9.xxx.xxx",
    "refresh_token": "oYQz7UA4jafCfYZN7BW1cX6Kn-QGxNf1XIxKp-xxx",
    "token_type": "Bearer",
    "expires_in": 86400
}

  • ❌包装数据格式

    自定义数据格式，像包含了业务码的，这种 Knife4j 是无法解析的，更没法去自动填充了。

    json 复制代码 
    {
    "code": "00000",
    "data": {
        "access_token": "eyJraWQiOiJlNTg1NTQ3MS02ZDlmLTRkOWEtODJlNi1mN2QyNjY4YjhhZDgiLCJhbGciOiJSUzI1NiJ9.xxx.xxx",
        "refresh_token": "ImW57MWPEBQpcNpuPsX1l5eJCDtyoBMz-xxx",
        "token_type": "Bearer",
        "expires_in": 86400
    },
    "msg": "一切ok"
}

client 是代码中为测试接口预留的一个客户端ID，具体可以看下 MyAuthenticationSuccessHandler 这个类的处理

获取登录用户信息

认证成功之后，打开 获取登录用户信息 接口 ，点击请求头部可以看到访问令牌已经自动填充到请求头的 Authorization 参数中了。

点击发送，可以看到数据成功返回。

输入错误的访问令牌，提示 "token无效或已过期"，符合预期效果。

结语

这篇文章首先介绍了如何将 Spring Cloud 微服务与 Knife4j 4.3 集成，借助 Spring Cloud Gateway 网关聚合各个服务的接口文档，实现了更统一的管理方式。最后，我们还探讨了如何在整合后的接口文档中测试 Spring Authorization Server 扩展的 OAuth2 密码模式认证接口，一旦认证成功，Knife4j 会自动填充访问令牌，使您能够轻松地访问其他接口。

到此，youlai-mall 新版本接口文档的整合和调试教程结束。希望这篇文章对您有所帮助，能够帮助您避免在使用新版本时遇到各种问题。

源码

Github Gitee
开源组织 有来开源组织 有来开源组织
后端 youlai-mall 📖 youlai-mall 📖
前端 mall-admin🌎 mall-admin 🌎
移动端 mall-app 🌎 mall-app 🌎
相关推荐
小雷FansUnion2 小时前
深入理解MCP架构：智能服务编排、上下文管理与动态路由实战
人工智能·架构·大模型·mcp
慌糖2 小时前
微服务介绍
微服务·云原生·架构
June bug3 小时前
【软考中级·软件评测师】下午题·面向对象测试之架构考点全析：分层、分布式、微内核与事件驱动
经验分享·分布式·职场和发展·架构·学习方法·测试·软考
森焱森6 小时前
无人机三轴稳定控制（2）____根据目标俯仰角，实现俯仰稳定化控制，计算出升降舵输出
c语言·单片机·算法·架构·无人机
沃夫上校7 小时前
Feign调Post接口异常：Incomplete output stream
java·后端·微服务
go54631584657 小时前
修改Spatial-MLLM项目，使其专注于无人机航拍视频的空间理解
人工智能·算法·机器学习·架构·音视频·无人机
阿里云云原生8 小时前
开启报名｜Nacos3.0 开源开发者沙龙·杭州场 Agent&MCP 专场
微服务
阿里云云原生8 小时前
阿里云可观测 2025 年 6 月产品动态
云原生
阿里云云原生8 小时前
30 秒锁定黑客攻击：SLS SQL 如何从海量乱序日志中“揪”出攻击源
云原生
凌辰揽月9 小时前
8分钟讲完 Tomcat架构及工作原理
java·架构·tomcat
热门推荐
01手机电脑之间快速传输图片视频文件，不压缩画质、不限制大小的方法！02Coze实战第13讲：飞书多维表格读取+豆包生图模型，轻松批量生成短剧封面03Coze扣子平台完整体验和实践（附国内和国际版对比）04免费可用！最强AI数字人对口型神器：让照片开口说话唱歌，支持多人对口型+全身动作，1分钟学会！（附保姆级教程）05C#调用WechatOCR.exe实现本地OCR文字识别06扣子（coze）实战|我用扣子搭建了一个自动分析小红薯笔记内容的AI应用|详细步骤拆解07华为昇腾 910B 部署 DeepSeek-R1 蒸馏系列模型详细指南08如何将markdown生成pdf09DeepSeek各版本说明与优缺点分析10Coze 全方位入门剖析 - 免费打造自己的 AI 超级个体