Spring Cloud 微服务项目如何聚合 API 文档?这波操作秀_
今天这篇文章介绍一下微服务如何聚合Swagger实现接口文档管理。
微服务模块众多,如果不聚合文档,则访问每个服务的API文档都需要单独访问一个Swagger UI界面,这么做客户端能否接受?
统一的文档入口显然应该聚合到网关中,通过网关的入口统一映射到各个模块。
本文采用Spring Cloud Gateway 聚合 Swagger 的 方式 生成API文档。
本文只介绍如何聚合Swagger,关于网关、注册中心等内容不再介绍,有不了解的看陈某前面文章。
单个服务聚合其实很简单,就是普通的Spring Boot 整合 Swagger,但是微服务模块众多,不能每个微服都整合一番,因此可以自定义一个swagger-starter,之后每个微服务都依赖这个starter即可。
对于Swagger原生的UI界面陈某不太喜欢,因此使用了一款看起来还不错的UI界面,依赖如下:
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<!--swagger-ui 这里是用了一个好看一点ui界面-->
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
陈某是将每个服务的API信息抽离出一个属性类SwaggerProperties,后续只需要在每个服务的配置文件中指定即可。
@ConfigurationProperties(prefix = SwaggerProperties.PREFIX)
@EnableConfigurationProperties
public class SwaggerProperties {
public static final String PREFIX="spring.swagger";
API文档配置无非就是配置文档的基本信息,比如文档标题、作者、联系方式.....
授权信息配置也很简单,就是在全局信息的请求头中配置一个能够放置令牌的地方,代码如下:
好了,swagger-starter关键代码就介绍完了,详细配置见源码。
项目源码地址:https://github.com/chenjiabing666/JavaFamily/tree/master/cloud-alibaba
<artifactId>swagger-starter</artifactId>
接下来只需要在配置文件配置API相关的信息即可,比如订单服务的配置如下:
此时我们可以验证一下,直接访问:http://localhost:3002/swagger-order-boot/v2/api-docs,结果如下图:
网关聚合的思想很简单,就是从路由中获取微服务的访问地址,然后拼接上 /v2/api-docs 即可。
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<!--swagger-ui 这里是用了一个好看一点ui界面-->
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
创建GatewaySwaggerResourcesProvider实现SwaggerResourcesProvider,重写其中的get方法,代码如下:
此时启动网关、订单、库存服务,直接访问网关的文档:http://localhost:3001/doc.html,结果如下图:
不得不说这款Swagger UI 界面还是比较简单易用的,个人用起来还不错。
在右上角的搜索功能可以根据接口描述搜索相关的接口信息,如下图:
可以直接拷贝文档的MarkDown形式转换成Html或者PDF生成离线文档,如下图:
在访问需要认证的接口时,可以通过配置令牌,这样令牌将会全局生效,不必每个请求都要配置一遍,如下:
该文档的所有配置,包括请求参数、授权令牌等信息都是缓存的,也就是说配置一次,下次再打开的时候也是默认存在的。
0条评论