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

谁践踏了优雅 2023-10-11 23:47 16阅读 0赞

#### 文章目录 ####

*  背景
 *  本地开发环境介绍
 *  pom.xml主要依赖
 *  application.yml
 *  效果预览
 *  动态生成swagger文档分组
 *  效果预览
 *  在线文档

## 背景 ##

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

> `SpringBoot 3.x`需要`SpringDoc 2.x`。

## 本地开发环境介绍 ##

<table> 
 <thead> 
  <tr> 
   <th align="left">开发依赖</th> 
   <th align="left">版本</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">Spring Boot</td> 
   <td align="left">3.0.6</td> 
  </tr> 
  <tr> 
   <td align="left">Spring Cloud</td> 
   <td align="left">2022.0.2</td> 
  </tr> 
  <tr> 
   <td align="left">Spring Cloud Alibaba</td> 
   <td align="left">2022.0.0.0-RC2</td> 
  </tr> 
  <tr> 
   <td align="left">Spring Doc</td> 
   <td align="left">2.1.0</td> 
  </tr> 
  <tr> 
   <td align="left">JDK</td> 
   <td align="left">20</td> 
  </tr> 
 </tbody> 
</table>

## pom.xml主要依赖 ##

<dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-gateway</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>
    
        
        <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`  
![在这里插入图片描述][9f80f6fd807a49929618fb3b668cf10f.png]

## 动态生成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文档

## 效果预览 ##

![在这里插入图片描述][4cb5b4cab1d944d98a3f35134f4c5b98.png]

## 在线文档 ##

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

[9f80f6fd807a49929618fb3b668cf10f.png]: https://img-blog.csdnimg.cn/9f80f6fd807a49929618fb3b668cf10f.png
[4cb5b4cab1d944d98a3f35134f4c5b98.png]: https://img-blog.csdnimg.cn/4cb5b4cab1d944d98a3f35134f4c5b98.png