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

本文涉及的产品
服务治理 MSE Sentinel/OpenSergo,Agent数量 不受限
云原生网关 MSE Higress,422元/月
MSE Nacos/ZooKeeper 企业版试用,1600元额度,限量50份
简介: 微服务如何聚合 API 文档?这波秀~

今天这篇文章介绍一下微服务如何聚合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,关注公众号:码猿技术专栏,回复关键: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方法,代码如下:

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

好了,网关的配置这里就完成了。

此时启动网关、订单、库存服务,直接访问网关的文档:http://localhost:3001/doc.html,结果如下图:

API文档好用的功能介绍

不得不说这款Swagger UI 界面还是比较简单易用的,个人用起来还不错。

1、搜索功能

在右上角的搜索功能可以根据接口描述搜索相关的接口信息,如下图:

2、离线文档

可以直接拷贝文档的MarkDown形式转换成Html或者PDF生成离线文档,如下图:

3、令牌配置

在访问需要认证的接口时,可以通过配置令牌,这样令牌将会全局生效,不必每个请求都要配置一遍,如下:

4、配置缓存

该文档的所有配置,包括请求参数、授权令牌等信息都是缓存的,也就是说配置一次,下次再打开的时候也是默认存在的。

5、全局参数配置

对于一些全局的参数,比如请求头中需要携带请求客户端、版本号等信息,可以在全局参数中配置,如下:

总结

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

相关文章
|
7天前
|
API 微服务
阿里云微服务引擎 MSE 及 API 网关 2025 年 9 月产品动态
阿里云微服务引擎 MSE 及 API 网关 2025 年 9 月产品动态。
|
17天前
|
运维 Cloud Native 应用服务中间件
阿里云微服务引擎 MSE 及 API 网关 2025 年 9 月产品动态
阿里云微服务引擎 MSE 面向业界主流开源微服务项目, 提供注册配置中心和分布式协调(原生支持 Nacos/ZooKeeper/Eureka )、云原生网关(原生支持Higress/Nginx/Envoy,遵循Ingress标准)、微服务治理(原生支持 Spring Cloud/Dubbo/Sentinel,遵循 OpenSergo 服务治理规范)能力。API 网关 (API Gateway),提供 APl 托管服务,覆盖设计、开发、测试、发布、售卖、运维监测、安全管控、下线等 API 生命周期阶段。帮助您快速构建以 API 为核心的系统架构.满足新技术引入、系统集成、业务中台等诸多场景需要。
|
23天前
|
人工智能 安全 架构师
告别旅行规划的"需求文档地狱"!这个AI提示词库,让你像调API一样定制完美旅程
作为开发者,旅行规划如同“需求地狱”:信息碎片、需求多变、缺乏测试。本文提出一套“企业级”AI提示词库,将模糊需求转化为结构化“API请求”,实现标准化输入输出,让AI成为你的专属旅行架构师,30分钟生成专业定制方案,提升决策质量,降低90%时间成本。
360 129
|
23天前
|
人工智能 API 监控
告别多接口拼凑!阿里云 API 模型聚合实现技术能力协同跃迁
API聚合整合400+国内外AI模型,统一接口、屏蔽差异,降低开发与维护成本,提升效率与系统稳定性,助力开发者高效应对多API调用困境。
182 0
API 微服务
54 0
|
2月前
|
运维 Cloud Native 应用服务中间件
阿里云微服务引擎 MSE 及 API 网关 2025 年 8 月产品动态
阿里云微服务引擎 MSE 面向业界主流开源微服务项目, 提供注册配置中心和分布式协调(原生支持 Nacos/ZooKeeper/Eureka )、云原生网关(原生支持Higress/Nginx/Envoy,遵循Ingress标准)、微服务治理(原生支持 Spring Cloud/Dubbo/Sentinel,遵循 OpenSergo 服务治理规范)能力。API 网关 (API Gateway),提供 APl 托管服务,覆盖设计、开发、测试、发布、售卖、运维监测、安全管控、下线等 API 生命周期阶段。帮助您快速构建以 API 为核心的系统架构.满足新技术引入、系统集成、业务中台等诸多场景需要。
203 15
|
3月前
|
API
阿里云微服务引擎 MSE 及 API 网关 2025 年 7 月产品动态
阿里云微服务引擎 MSE 及 API 网关 2025 年 7 月产品动态
|
3月前
|
运维 Cloud Native 应用服务中间件
阿里云微服务引擎 MSE 及 API 网关 2025 年 7 月产品动态
阿里云微服务引擎 MSE 面向业界主流开源微服务项目, 提供注册配置中心和分布式协调(原生支持 Nacos/ZooKeeper/Eureka )、云原生网关(原生支持Higress/Nginx/Envoy,遵循Ingress标准)、微服务治理(原生支持 Spring Cloud/Dubbo/Sentinel,遵循 OpenSergo 服务治理规范)能力。API 网关 (API Gateway),提供 APl 托管服务,覆盖设计、开发、测试、发布、售卖、运维监测、安全管控、下线等 API 生命周期阶段。帮助您快速构建以 API 为核心的系统架构.满足新技术引入、系统集成、业务中台等诸多场景需要。
|
3月前
|
缓存 监控 API
电商API的微服务架构优化策略
随着电商快速发展,API成为连接用户、商家与系统的核心。本文探讨微服务架构下电商API的优化策略,分析高并发、低延迟与数据一致性等挑战,并提供服务拆分、缓存异步、监控容器化等实践方案,助力构建高性能、高可用的电商系统,提升用户体验与业务效率。
90 0
|
3月前
|
Cloud Native API
微服务引擎 MSE 及云原生 API 网关 2025 年 6 月产品动态
微服务引擎 MSE 及云原生 API 网关 2025 年 6 月产品动态

热门文章

最新文章