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

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 🌎
相关推荐
非优秀程序员6 分钟前
未来的编程将会是什么样子?从面向对象转为面向业务数据!!
数据库·架构
文火冰糖的硅基工坊32 分钟前
[硬件电路-97]:模拟器件 - 如何通过外部的闭环负反馈,让运算放大器从“暴脾气”、“愣头青”、情绪容易失控者变成“沉着”、“冷静”的精密调控者的?
嵌入式硬件·架构·电路·跨学科融合
东风微鸣32 分钟前
提升效率:AI 知识库在软件开发中的应用
docker·云原生·kubernetes·可观察性
Lyndon110733 分钟前
K8S 八 数据存储-高级存储PV PVC 生命周期;配置存储ConfigMap Secret
云原生·容器·kubernetes
●VON1 小时前
重生之我在暑假学习微服务第二天《MybatisPlus-下篇》
java·学习·微服务·架构·mybatis-plus
秋千码途1 小时前
小架构step系列27:Hibernate提供的validator
java·spring·架构·hibernate
Hermann3 小时前
云原生系统健壮性浅谈
架构·云计算
白-胖-子9 小时前
深入剖析大模型在文本生成式 AI 产品架构中的核心地位
人工智能·架构
武子康9 小时前
Java-80 深入浅出 RPC Dubbo 动态服务降级:从雪崩防护到配置中心秒级生效
java·分布式·后端·spring·微服务·rpc·dubbo
Pomelo_刘金12 小时前
用 DDD 把「闹钟」需求一点点捏出来
架构·rust·领域驱动设计