今天这篇文章介绍微服务如何聚合Swagger实现接口文档管理。文章目录如下：为什么需要聚合？有很多微服务模块。如果不聚合文档，需要单独访问一个SwaggerUI接口来访问各个服务的API文档。客户能接受吗？反正作为强迫症的我是不能接受的....既然用了微服务，就应该有一个统一的API文档入口。如何聚合？统一的文档入口显然应该聚合到网关中，网关的入口应该统一映射到各个模块。演示本文使用SpringCloudGateway聚合Swagger生成API文档。案例源码结构如下：本文只介绍如何聚合Swagger，不会介绍网关、注册中心等，不明白的请看陈老师上一篇文章。单个服务如何聚合Swagger？这里的单服务不包括网关，需要单独配置。单个服务聚合其实很简单，就是普通的SpringBoot集成了Swagger，但是微服务模块很多，每个微服务无法集成，所以可以自定义一个swagger-starter，然后每个微服务都依赖这个starter。.详细步骤如下：1.创建swagger-starter自定义starter这里就不介绍了，都是基础知识；目录结构如下：1）添加依赖Chen不喜欢Swagger原生的UI界面，所以他使用了一个看起来还不错的UI界面，依赖如下：io.springfoxspringfox-boot-startercom.github.xiaoyminswagger-bootstrap-uiUI界面，每个人的审美不同，选择自己喜欢的就好。2）自动配置类配置SwaggerChen是将各个服务的API信息提取到一个属性类SwaggerProperties中，然后只需要在各个服务的配置文件中指定即可。@Data@ConfigurationProperties(prefix=SwaggerProperties.PREFIX)@Component@EnableConfigurationPropertiespublicclassSwaggerProperties{publicstaticfinalStringPREFIX="spring.swagger";//封装privateStringbasePackage;//作者相关信息privateAuthorauthor;//API相关信息privateApiInfoapiInfo;@DatapublicstaticclassApiInfo{字符串标题；字符串描述；字符串版本；字符串termsOfServiceUrl；字符串许可证；字符串licenseUrl;}@DatapublicstaticclassAuthor{私有字符串名称；私人字符串电子邮件；私有字符串url；}}Swagger的配置其实很简单，分为以下几个部分：API文档基本信息配置授权信息配置（基于OAuth2的认证配置）API文档配置无非就是配置文档的基本信息，比如documenttitle,author,contactinformation.....代码如下：授权信息的配置也很简单，就是在全局信息的请求头配置一个可以放token的地方。令牌可以在这里设置。好了，swagger-starter的关键代码介绍完毕，详细配置见源码。2、微服务引用swagger-starter单微服务引用很简单，只需要添加如下依赖：@Data@ConfigurationProperties(prefix=SwaggerProperties.PREFIX)@Component@EnableConfigurationPropertiespublicclassSwaggerProperties{publicstaticfinalStringPREFIX="spring.swagger";//包privateStringbasePackage;//作者相关信息privateAuthorauthor;//API相关信息privateApiInfoapiInfo;@DatapublicstaticclassApiInfo{字符串标题；字符串描述；字符串版本；字符串termsOfServiceUrl；字符串许可证；字符串licenseUrl；}@DatapublicstaticclassAuthor{私有字符串名称；私人字符串电子邮件；私人字符串网址；}}接下来只需要在配置文件中配置API相关的信息即可，例如订单服务的配置如下：OK，至此单个服务的配置就完成了。此时我们可以验证一下，直接访问：http://localhost:3002/swagger-order-boot/v2/api-docs，结果如下：网关是如何聚合Swagger的？网关聚合的思路很简单，就是从路由中获取微服务的访问地址，然后拼接/v2/api-docs。同样需要添加两个Swagger的依赖，如下：io.springfoxspringfox-boot-startercom.github.xiaoyminswagger-bootstrap-ui创建GatewaySwaggerResourcesProvider实现SwaggerResourcesProvider，重写get方法，代码如下：》好了，网关的配置到这里就完成了，此时启动网关、订单、库存服务，直接访问网关的文档：http://localhost:3001/doc.html，结果如下图：API文档的有用功能介绍不得不说这个SwaggerUI界面比较简单易用，而且它个人用还不错1.右上角的搜索功能可以根据界面描述进行搜索搜索相关接口信息，如下图：2.离线文档可以直接复制文档的MarkDown格式，转成Html或PDF生成离线文档，如下图：3.Token配置在访问需要认证的接口时，可以通过配置命令card，这样token会全局生效，不需要每次请求都配置，如下：4.配置缓存文件的所有配置，包括请求参数，授权token等信息都被缓存了，也就是说配置一次，下次打开的时候也会默认存在。5.全局参数配置对于一些全局参数，比如请求头中需要携带请求客户端、版本号等信息，可以在全局参数中进行配置，如下：本文小结文章介绍微服务集成网关聚合Swagger文档，开发中非常实用。
