乐趣区

关于java:微服务如何聚合-API-文档这波秀

jiezi

大家好，我是不才陈某~

这是《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 界面，每个人审美不同，抉择本人喜爱的就好。

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 的配置其实很简略，分为如下局部：

  1. API 文档根本信息配置
  2. 受权信息配置（基于 OAuth2 的认证配置）

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

代码如下：

受权信息配置也很简略，就是在全局信息的申请头中配置一个可能搁置令牌的中央，代码如下：

此处对应 UI 界面的中央如下图：

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

好了，swagger-starter 要害代码就介绍完了，具体配置见源码。

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

2、微服务援用 swagger-starter

单个微服务援用就很简略了，只须要增加如下依赖：

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

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

好了，至此单个服务的配置实现了。

此时咱们能够验证一下，间接拜访：http://localhost:3002/swagger…，后果如下图：

网关如何聚合 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 办法，代码如下：

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

好了，网关的配置这里就实现了。

此时启动网关、订单、库存服务，间接拜访网关的文档：http://localhost:3001/doc.html，后果如下图：

API 文档好用的性能介绍

不得不说这款 Swagger UI 界面还是比较简单易用的，集体用起来还不错。

1、搜寻性能

在右上角的搜寻性能能够依据接口形容搜寻相干的接口信息，如下图：

2、离线文档

能够间接拷贝文档的 MarkDown 模式转换成 Html 或者 PDF 生成离线文档，如下图：

3、令牌配置

在拜访须要认证的接口时，能够通过配置令牌，这样令牌将会全局失效，不用每个申请都要配置一遍，如下：

4、配置缓存

该文档的所有配置，包含申请参数、受权令牌等信息都是缓存的，也就是说配置一次，下次再关上的时候也是默认存在的。

5、全局参数配置

对于一些全局的参数，比方申请头中须要携带申请客户端、版本号等信息，能够在全局参数中配置，如下：

总结

本篇文章介绍了微服务集成网关聚合 Swagger 文档，开发中十分实用。

最初说一句（别白嫖，求关注）

陈某每一篇文章都是精心输入，曾经写了 3 个专栏，整顿成PDF，获取形式如下：

  1. 《Spring Cloud 进阶》PDF：关注公众号：【码猿技术专栏】回复关键词 Spring Cloud 进阶 获取！
  2. 《Spring Boot 进阶》PDF：关注公众号：【码猿技术专栏】回复关键词 Spring Boot 进阶 获取！
  3. 《Mybatis 进阶》PDF：关注公众号：【码猿技术专栏】回复关键词 Mybatis 进阶 获取！

如果这篇文章对你有所帮忙，或者有所启发的话，帮忙 点赞 、 在看 、 转发 、 珍藏，你的反对就是我坚持下去的最大能源！

关注公众号：【码猿技术专栏】，公众号内有超赞的粉丝福利，回复：加群，能够退出技术探讨群，和大家一起探讨技术，吹牛逼！

退出移动版