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

爱撒谎的男孩

发布于 2023-08-28 14:32:36

2020

发布于 2023-08-28 14:32:36

文章被收录于专栏：码猿技术专栏码猿技术专栏

为什么需要聚合？

微服务模块众多，如果不聚合文档，则访问每个服务的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界面，每个人审美不同，选择自己喜欢的就好。

2、自动配置类配置Swagger

陈某是将每个服务的API信息抽离出一个属性类SwaggerProperties，后续只需要在每个服务的配置文件中指定即可。

@Data
@ConfigurationProperties(prefix = SwaggerProperties.PREFIX)
@Component
@EnableConfigurationProperties
public class SwaggerProperties {
    public static final String PREFIX="spring.swagger";

    //包
    private String basePackage;

    //作者相关信息
    private Author author;

    //API的相关信息
    private ApiInfo apiInfo;

    @Data
    public static class ApiInfo{
        String title;
        String description;
        String version;
        String termsOfServiceUrl;
        String license;
        String licenseUrl;
    }
    @Data
    public static class Author{
        private String name;

        private String email;

        private String url;
    }
}

对于Swagger的配置其实很简单，分为如下部分：

API文档基本信息配置
授权信息配置（基于OAuth2的认证配置）

API文档配置无非就是配置文档的基本信息，比如文档标题、作者、联系方式…..

代码如下：

授权信息配置也很简单，就是在全局信息的请求头中配置一个能够放置令牌的地方，代码如下：

此处对应UI界面的地方如下图：

只需要将获取token令牌设置到这里即可。

好了，swagger-starter关键代码就介绍完了，详细配置见源码。

案例源码已上传GitHub，关注公众号：码猿技术专栏，回复关键：9528 获取！

2、微服务引用swagger-starter

单个微服务引用就很简单了，只需要添加如下依赖：

<dependency>
  <groupId>cn.myjszl</groupId>
  <artifactId>swagger-starter</artifactId>
</dependency>

接下来只需要在配置文件配置API相关的信息即可，比如订单服务的配置如下：

好了，至此单个服务的配置完成了。

此时我们可以验证一下，直接访问：http://localhost:3002/swagger-order-boot/v2/api-docs，结果如下图：

网关如何聚合Swagger？

网关聚合的思想很简单，就是从路由中获取微服务的访问地址，然后拼接上 /v2/api-docs 即可。

同样的还是要添加Swagger的两个依赖，如下：

<!--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>

创建GatewaySwaggerResourcesProvider实现SwaggerResourcesProvider，重写其中的get方法，代码如下：