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:falsesetting:language: zh_cn

SwaggerConfig.java

packagecom.youlai.system.config;importio.swagger.v3.oas.models.Components;importio.swagger.v3.oas.models.OpenAPI;importio.swagger.v3.oas.models.info.Info;importio.swagger.v3.oas.models.info.License;importio.swagger.v3.oas.models.security.OAuthFlow;importio.swagger.v3.oas.models.security.OAuthFlows;importio.swagger.v3.oas.models.security.SecurityRequirement;importio.swagger.v3.oas.models.security.SecurityScheme;importorg.springframework.beans.factory.annotation.Value;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importorg.springframework.http.HttpHeaders;/**
 * Swagger 配置类
 * <p>
 * 基于 OpenAPI 3.0 规范 + SpringDoc 实现 + knife4j 增强
 *
 * @author haoxr
 * @since 3.0.0
 */@ConfigurationpublicclassSwaggerConfig{/**
     * OAuth2 认证 endpoint
     */@Value("${spring.security.oauth2.authorizationserver.token-uri}")privateString tokenUrl;/**
     * OpenAPI 配置（元信息、安全协议）
     */@BeanpublicOpenAPIapiInfo(){returnnewOpenAPI().components(newComponents().addSecuritySchemes(HttpHeaders.AUTHORIZATION,newSecurityScheme()// OAuth2 授权模式.type(SecurityScheme.Type.OAUTH2).name(HttpHeaders.AUTHORIZATION).flows(newOAuthFlows().password(newOAuthFlow().tokenUrl(tokenUrl).refreshUrl(tokenUrl)))// 安全模式使用Bearer令牌（即JWT）.in(SecurityScheme.In.HEADER).scheme("Bearer").bearerFormat("JWT")))// 接口全局添加 Authorization 参数.addSecurityItem(newSecurityRequirement().addList(HttpHeaders.AUTHORIZATION))// 接口信息定义.info(newInfo().title("系统服务").version("3.0.0").description("用户、角色、菜单、部门、字典等接口").license(newLicense().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:truelower-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 新版本接口文档的整合和调试教程结束。希望这篇文章对您有所帮助，能够帮助您避免在使用新版本时遇到各种问题。

源码

GithubGitee开源组织有来开源组织有来开源组织后端youlai-mall 📖youlai-mall 📖前端mall-admin🌎mall-admin 🌎移动端mall-app 🌎mall-app 🌎