Spring Cloud Gateway + Knife4j 4.3 接口文档整合和网关聚合

前言

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

<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

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

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

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-gateway-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

application.yml

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 自动填充请求头前提需要数据原生返回，那么什么是原生数据格式？

• ✔️原生数据格式

  {
      "access_token": "eyJraWQiOiJlNTg1NTQ3MS02ZDlmLTRkOWEtODJlNi1mN2QyNjY4YjhhZDgiLCJhbGciOiJSUzI1NiJ9.xxx.xxx",
      "refresh_token": "oYQz7UA4jafCfYZN7BW1cX6Kn-QGxNf1XIxKp-xxx",
      "token_type": "Bearer",
      "expires_in": 86400
  }
  

• ❌包装数据格式

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

  {
      "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 新版本接口文档的整合和调试教程结束。希望这篇文章对您有所帮助，能够帮助您避免在使用新版本时遇到各种问题。

源码