【Spring Cloud Gateway】⑥SpringBoot3.x集成SpringDoc指南

背景

Spring Cloud Gateway使用Netty作为嵌入式服务器，并基于响应式Spring WebFlux。做为微服务网关，多个微服务把API挂在Gateway上，如果查看某个API的Swagger还要去各个子微服务中去查看，就很不方便，如果能在Gateway上直接查看各个微服务的API文档，会方便很多，本文以截至目前最新的版本为示例，讲解如何在Spring Cloud Gateway中集成SpringDoc。

SpringBoot 3.x需要SpringDoc 2.x。

本地开发环境介绍

开发依赖	版本
Spring Boot	3.0.6
Spring Cloud	2022.0.2
Spring Cloud Alibaba	2022.0.0.0-RC2
Spring Doc	2.1.0
JDK	20

pom.xml主要依赖

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-gateway</artifactId>
    </dependency>
    <!--引⼊webflux-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>

    <!-- webflux+SpringDoc -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-common</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    </dependency>
</dependencies>

application.yml

spring:
  application:
    name: demo-gateway
  cloud:
    gateway:
      api-prefix: /
      #路由配置
      routes:
        - id: wen3-framework-apidoc-springdoc-demo
          uri: http://localhost:7001
          predicates:
            - Path=/demo7001/**
          filters:
            - RewritePath=/demo7001/(?<path>.*), /$\{
    
    path}
        - id: openapi
          uri: http://localhost:${
    
    server.port}
          predicates:
            - Path=/v3/api-docs/**
          filters:
            - RewritePath=/v3/api-docs/(?<path>.*), /$\{
    
    path}/api-docs
  
######## swagger configuration ###############
springdoc:
  swagger-ui:
    urls:
      - name: demo7001
        url: /v3/api-docs/demo7001

• demo7001是另一个SpringDoc演示服务，可以通过/api-docs获取swagger JSON数据即可
• 如果有多个服务，就需要添加多个routes
• 原理是通过调用微服务本身文档接口获取JSON数据，然后在网关的swagger-ui页面上展示

效果预览

浏览器访问http://localhost:8081/swagger-ui.html

动态生成swagger文档分组

package com.wen3.demo.gateway.springdoc;

import lombok.extern.slf4j.Slf4j;
import org.springdoc.core.properties.AbstractSwaggerUiConfigProperties;
import org.springdoc.core.properties.SwaggerUiConfigProperties;
import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.stereotype.Component;
import org.springframework.util.CollectionUtils;

import java.util.HashSet;

@Component
@Slf4j
public class SwaggerUiConfigPropertiesPostProcessor implements BeanPostProcessor {
    
    
    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
    
    
        if(SwaggerUiConfigProperties.class.isAssignableFrom(bean.getClass())) {
    
    
            SwaggerUiConfigProperties obj = (SwaggerUiConfigProperties) bean;
            if(CollectionUtils.isEmpty(obj.getUrls())) {
    
    
                obj.setUrls(new HashSet<>());
            }
            obj.getUrls().add(new AbstractSwaggerUiConfigProperties.SwaggerUrl("demo7001", "/v3/api-docs/demo7001", "demo7001xx"));
        }
        return BeanPostProcessor.super.postProcessBeforeInitialization(bean, beanName);
    }
}

• 可以根据需要改造这个功能，可以在从routes配置中解析各个微服务，然后添加每个微服务的swagger文档
• 也可以从数据库或其它地方获取需要开启的swagger文档

效果预览

在线文档

• 官网: https://springdoc.org/#getting-started