原理简介
在网关中配置好路由
Spring Cloud Gatway + Springfox
- 第一步、在各项目里配置Springfox
- 第二步、在网关中编写api文档资源路径
- 注意
Spring Cloud Gatway + Springdoc
- 第一步、引入依赖
- 第二步、手动配置api文档路径
- 第三步、使用重写路径过滤器转换路径

本文简单介绍在Spring Cloud Gateway项目里聚合多个微服务的swagger文档的实践经验。

在聚合各个微服务的api文档之前，您自然已经搭建好了微服务开发的框架，所以各个微服务项目里的服务注册与发现应该都已经配置好了。Swagger框架可以选用Springfox或Springdoc

原理简介

我们知道Swagger或着说后来的openApi是一种描述api接口文档的规范。每个使用了swagger的项目，在/v2/api-docs或/v3/api-docs路径下都可以看到该项目所有的接口描述。但是由于每个微服务的项目部署的ip地址和端口都不一样，所以需要分别访问每个项目的文档路径才能看到相应的地址，这是不方便的。现在我们使用了网关，而网关又有请求转发的功能，所以我们可以在网关的项目里，手动设置各个微服务swagger文档的资源路径，只是ip地址和端口都变成网关微服务的了。然后当我们向网关请求某个微服务api文档的路径时，网关会自动转发到对应的服务上。

在网关中配置好路由

spring:cloud:gateway:discovery:locator:enabled: true #开启网关的服务发现routes:- id: 配置路由iduri: lb://微服务名 #注意这里的格式order: -1predicates:- filters:-

Spring Cloud Gatway + Springfox

文档地址：http://springfox.github.io/springfox/docs/current/

第一步、在各项目里配置Springfox

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

使用Swaager2和Swagger3时，这两个地方设置不一样。

第二步、在网关中编写api文档资源路径

package cn.com.nbd.app.gateway.config;import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;import java.util.ArrayList;
import java.util.List;/*** <p>描述：</p>** @author 木刀* @since 2022/3/17 15:57*/
@Component
@Primary
//springfox提供了一个接口SwaggerResourcesProvider，用户可自行编写api资源，这正是我们需要的。
public class GatewaySwaggerResourcesProvider implements SwaggerResourcesProvider {public static final String API_URI = "/v3/api-docs"; //swagger2对应的是/v2/api-docs@Value("${spring.application.name}")private String gatewayApplicationName;@Autowiredprivate RouteLocator routeLocator;@Overridepublic List<SwaggerResource> get() {//保存我们手动设置的api文档资源信息List<SwaggerResource> resources = new ArrayList<>();//取出gateway的routerouteLocator.getRoutes()//将除了网关外的其他微服务对应的路由筛选出来.filter(route -> route.getUri().getHost() != null&& !gatewayApplicationName.equals(route.getUri().getHost())&& !route.getId().startsWith("ReactiveCompositeDiscoveryClient")).subscribe(route -> {//获取对应路由的servlet.context-pathcontextPath = route.getUri().getHost();//拼接对应微服务的api文档路径，每个微服务对应一个SwaggerResource，但这里的路径的ip地址和端口是网关的，所以我们在网关的swagger-ui中可以看到。然后由网关转发到对应的微服务地址去。resources.add(swaggerResource(route.getId(),"/" + contextPath + API_URI));});return resources;}private SwaggerResource swaggerResource(String name, String url) {SwaggerResource swaggerResource = new SwaggerResource();swaggerResource.setName(name);swaggerResource.setUrl(url);swaggerResource.setSwaggerVersion("3.0");return swaggerResource;}
}

注意

截止2022/4/3,spring boot 2.6以上的版本使用springfox会出现问题
spring boot 2.6以上版本+spingfox 3.0会出现一个问题，
Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException
目前还没有解决办法，有成功解决的希望可以分享在评论里。
swagger 3.0不需要为每个路由配置过滤器StripPrefix=1，否则会出现：Fetch errorNot Found

Spring Cloud Gatway + Springdoc

文档地址：https://springdoc.org/

第一步、引入依赖

在网关项目里引入：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-webflux-ui</artifactId><version>1.6.6</version></dependency>

在其他项目里：

如果是servlet:
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-webmvc-core</artifactId><version>1.6.6</version></dependency>如果的webflux:
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-webflux-core</artifactId><version>1.6.6</version></dependency>

第二步、手动配置api文档路径

/*** <p>描述：</p>** @author 木刀* @since 2022/4/1 13:28*/
@Configuration
public class SpringDocConfig {@Bean@Lazy(false)public List<GroupedOpenApi> apis(SwaggerUiConfigParameters swaggerUiConfigParameters, RouteDefinitionLocator locator) {List<GroupedOpenApi> groups = new ArrayList<>();//仍然是通过路由定义获取context-pathlocator.getRouteDefinitions().filter(route -> route.getUri().getHost() != null&& !gatewayApplicationName.equals(route.getUri().getHost())&& !route.getId().startsWith("ReactiveCompositeDiscoveryClient")).subscribe(routeDefinition -> {contextPath = route.getUri().getHost();swaggerUiConfigParameters.addGroup(name);groups.add(GroupedOpenApi.builder().pathsToMatch("/" + contextPath + "/**").group(name).build());});return groups;}

第三步、使用重写路径过滤器转换路径

springdoc中，我们手动设置的aip文档路径最后生成的格式为/v3/api-docs/{contextPath}，所以我们需要把他转换成:/{contextPath}/v3/api-docs，可以借助网关中的路径重写过滤器。

- id: openapiuri: http://localhost:${server.port}order: -2 #该路由的优先级最后高于其他微服务的路由predicates:- Path=/v3/api-docs/**filters:- RewritePath=/v3/api-docs/(?<path>.*), /$\{path}/v3/api-docs

SpringCloud微服务项目的api文档聚合相关推荐

Maven学习总结（43）——利用javadoc插件生成项目的API文档
在进行Java学习的时候,相信大家都看过在线或者下载的java api文档,可能是html格式或者chm格式的,其实这些参考文档也是很容易生成的,这里介绍一个maven的插件来实现项目代码文档的生成. ...
高性能微服务网关APISIX - API文档
Admin API Description Admin API 是为 Apache APISIX 服务的一组 API,我们可以将参数传递给 Admin API 以控制 APISIX 节点.更好地了解其 ...
2021/04/25 SpringBoot + SpringCloud微服务项⽬交付案例
第1章 SpringBoot + SpringCloud微服务项⽬交付案例 1.1 微服务概念传统的是用户通过终端链接到应用里现在服务往越来越小的方向做,把每个服务做成一个独立的功能,每个服务完成 ...
springcloud gateway结合knife4j生成Api文档
springcloud gateway结合knife4j生成Api文档学习中笔记一. 接口模块(mxm-system-api)引入依赖 <dependency><groupId& ...
如何生成项目的chm文档
如何生成项目的chm文档 2014-11-30 Generate .chm based documentation of your project using SandCastle tool 转载于 ...
javaee 中文帮助文档_大牛耗时三天整理的：微服务+Nginx+Kubernetes实战文档和面试题...
前言十年之前,相信大家掌握了Java EE互联网轻量级框架整合开发 SSM框架SpringMVC+Spring+MyBatis就已经能够轻轻松松找到一份薪资很高的java开发工作了,而如今只会SSM ...
25岁阿里120W年薪架构师推荐学习的750页微服务架构深度解析文档
前言当前,微服务架构在国内正处于蓬勃发展的阶段,无论是大型互联网公司还是传统的IT企业,纷纷采用微服务架构构建系统. 在过去几年里,DevOps.云原生.面向演进式架构等理念已经深入人心,围绕微服务 ...
超全，看完这份微服务架构与实践文档，微服务不再难
前言: 微服务近年来受到了极大的关注并成为趋势,不信的话可以查看 Google Trends. 可以看到从2014年开始人们对它产生了极大的兴趣,随着时间的推移,这一趋势仍在增长. 随着数字化转型的推 ...
微服务项目构建标准文档
一搭建自己的微服务项目 1.1.1 搭建一个基于Spring Boot框架的Maven子项目我们在微服务架构上选择的是maven的父子项目,父项目的名称是cloud. 点击cloud ...

SpringCloud微服务项目的api文档聚合

目录