微服务如何聚合 API 文档？这波秀~（一）

大家好，我是不才陈某~

这是《Spring Cloud 进阶》第22篇文章，往期文章如下：

• 五十五张图告诉你微服务的灵魂摆渡者Nacos究竟有多强？
• openFeign夺命连环9问，这谁受得了？
• 阿里面试这样问：Nacos、Apollo、Config配置中心如何选型？这10个维度告诉你！
• 阿里面试败北：5种微服务注册中心如何选型？这几个维度告诉你！
• 阿里限流神器Sentinel夺命连环 17 问？
• 对比7种分布式事务方案，还是偏爱阿里开源的Seata，真香！(原理+实战)
• Spring Cloud Gateway夺命连环10问？
• Spring Cloud Gateway 整合阿里 Sentinel网关限流实战！
• 分布式链路追踪之Spring Cloud Sleuth夺命连环9问？
• 链路追踪自从用了SkyWalking，睡的真香！
• 3本书了，7万+字，10篇文章，《Spring Cloud 进阶》基础版 PDF
• 妹子始终没搞懂OAuth2.0，今天整合Spring Cloud Security 一次说明白！
• OAuth2.0实战！使用JWT令牌认证！
• OAuth2.0实战！玩转认证、资源服务异常自定义这些骚操作！
• 实战干货！Spring Cloud Gateway 整合 OAuth2.0 实现分布式统一认证授权！
• 字节面试这样问：跨库多表存在大量数据依赖问题有哪些解决方案？
• 实战！退出登录时如何借助外力使JWT令牌失效？
• 实战！Spring Cloud Gateway集成 RBAC 权限模型实现动态权限控制！
• 实战！阿里神器 Seata 实现 TCC模式 解决分布式事务，真香！
• 实战！openFeign如何实现全链路JWT令牌信息不丢失？
• 微服务下蓝绿发布、滚动发布、灰度发布等方案，必须懂！

今天这篇文章介绍一下微服务如何聚合Swagger实现接口文档管理。

文章目录如下：

 
为什么需要聚合？
微服务模块众多，如果不聚合文档，则访问每个服务的API文档都需要单独访问一个Swagger UI界面，这么做客户端能否接受？

反正作为强迫症的我是接受不了.......

既然使用了微服务，就应该有统一的API文档入口。

如何聚合？
统一的文档入口显然应该聚合到网关中，通过网关的入口统一映射到各个模块。

演示

本文采用Spring Cloud Gateway 聚合 Swagger 的 方式 生成API文档。

案例源码结构如下：

 
本文只介绍如何聚合Swagger，关于网关、注册中心等内容不再介绍，有不了解的看陈某前面文章。

单个服务如何聚合Swagger？
这里的单个服务不包括网关，网关需要单独配置。

单个服务聚合其实很简单，就是普通的Spring Boot 整合 Swagger，但是微服务模块众多，不能每个微服都整合一番，因此可以自定义一个swagger-starter，之后每个微服务都依赖这个starter即可。

详细的步骤如下：

1、创建swagger-starter

自定义starter这里就不再介绍了，都是基础的知识；

目录结构如下：

 
1、添加依赖

对于Swagger原生的UI界面陈某不太喜欢，因此使用了一款看起来还不错的UI界面，依赖如下：

<!--swagger-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
</dependency>

<!--swagger-ui  这里是用了一个好看一点ui界面-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

“对于UI界面，每个人审美不同，选择自己喜欢的就好。”

文章转自公众号：码猿技术专栏