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

简介: Spring Cloud Gateway 网关整合 Knife4j 4.3 实现微服务接口文档聚合

开局一张图

1.png

前言


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 ,访问页面如下:

2.pngSpring 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 ,访问页面如下图:

3.png

接口测试


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


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


登录认证


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

4.png

特别提醒: 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 这个类的处理

5.png

获取用户信息


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

6.png

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

7.png

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

8.png

结语


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


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


源码

相关文章
|
8天前
|
负载均衡 Nacos 数据安全/隐私保护
SpringCloud GateWay 使用
SpringCloud GateWay 使用
16 0
|
28天前
|
SpringCloudAlibaba Java 持续交付
【构建一套Spring Cloud项目的大概步骤】&【Springcloud Alibaba微服务分布式架构学习资料】
【构建一套Spring Cloud项目的大概步骤】&【Springcloud Alibaba微服务分布式架构学习资料】
123 0
|
28天前
|
SpringCloudAlibaba Java 网络架构
【Springcloud Alibaba微服务分布式架构 | Spring Cloud】之学习笔记(七)Spring Cloud Gateway服务网关
【Springcloud Alibaba微服务分布式架构 | Spring Cloud】之学习笔记(七)Spring Cloud Gateway服务网关
76 0
|
14天前
|
负载均衡 网络协议 Java
构建高效可扩展的微服务架构:利用Spring Cloud实现服务发现与负载均衡
本文将探讨如何利用Spring Cloud技术实现微服务架构中的服务发现与负载均衡,通过注册中心来管理服务的注册与发现,并通过负载均衡策略实现请求的分发,从而构建高效可扩展的微服务系统。
|
28天前
|
SpringCloudAlibaba 负载均衡 Java
【Springcloud Alibaba微服务分布式架构 | Spring Cloud】之学习笔记(目录大纲)
【Springcloud Alibaba微服务分布式架构 | Spring Cloud】之学习笔记(目录大纲)
61 1
|
28天前
|
Java Nacos Sentinel
【Springcloud Alibaba微服务分布式架构 | Spring Cloud】之学习笔记(九)Nacos+Sentinel+Seata
【Springcloud Alibaba微服务分布式架构 | Spring Cloud】之学习笔记(九)Nacos+Sentinel+Seata
162 0
|
28天前
|
消息中间件 SpringCloudAlibaba Java
【Springcloud Alibaba微服务分布式架构 | Spring Cloud】之学习笔记(八)Config服务配置+bus消息总线+stream消息驱动+Sleuth链路追踪
【Springcloud Alibaba微服务分布式架构 | Spring Cloud】之学习笔记(八)Config服务配置+bus消息总线+stream消息驱动+Sleuth链路追踪
771 0
|
19天前
|
Java 应用服务中间件 Maven
SpringBoot 项目瘦身指南
SpringBoot 项目瘦身指南
37 0
|
2月前
|
缓存 Java Maven
Spring Boot自动配置原理
Spring Boot自动配置原理
46 0
|
27天前
|
缓存 安全 Java
Spring Boot 面试题及答案整理,最新面试题
Spring Boot 面试题及答案整理,最新面试题
104 0