1、分布式接口文档聚合,是什么?
如果你有 "22" 个不同的服务(比如微服务),每个服务都有自己的接口文档。每个服务的文档各自打开,估计你会觉得很麻烦的?
再如果,它们是用 openapi 规范的。现在,可以通过一个服务去聚合它们。就是,在一个地址里,打开 "22" 个服务的接口文档。
2、认识 Solon-Docs
solon-docs,是 solon 的接口文档解决方案。它通过 DocDocket 申明文档摘要。支持 swagger 注解,或者 javadoc 注释,或者别的(可适配)。
从文档网关的角度(此文讲聚合嘛),只需使用 groupName, basicAuth, upstream 三个配置项,就可以接入外部服务的接口文档:
java
@Configuration
public class DocConfig {
@Bean("appApi")
public DocDocket appApi() {
return new DocDocket()
.groupName("app端接口")
.version("2.0") //可选,默认是 2.0
.basicAuth("admin", "1234") //可选(添加 basic auth 验证)
.upstream("http://demo.com.cn", "/demo", "swagger/v2?group=appApi");
}
}
upstream
配置值,切不要连接自己(否则,可能会死循环),其属性有:
属性 | 说明 |
---|---|
service | 目标服务名 |
contextPath | 服务上下文路径(在网关处,方便识别是哪个服务的,进而调用) |
uri | 接口文档地址 |
solon-docs 也可以通过 solon.docs
配置,完成 DocDocket 自动构建。
3、了解 solon.docs
配置格式自动构建
使用 solon.docs
配置,可以替代 solon bean 的构建方式。格式如下
yml
solon.docs:
discover:
uriPattern: "swagger/v2?group={service}" #目标服务的文档接口路径模式(要么带变量 {service},要么用统一固定值)
syncStatus: false #同步目标服务上下线状态(如果下线,则文档不显示)
basicAuth: #可选
admin: 1234
excluded: #排除目标服务名
- "xx"
included: #包括目标服务名
- "yy"
routes:
name1: DocDocket
name2: DocDocket
discover 配置项是专为聚合便利设计的,方便通过注册与发现服务聚合文档。格式说明:
配置名 | 说明 |
---|---|
discover | 用于配置分布式发现服务相关的(即,自动配置文档) |
discover.uriPattern | 目标服务的文档接口路径模式,支持{service} 占位符 |
discover.syncStatus | 同步目标服务上下线状态 |
discover.basicAuth | 添加 basic auth 验证(同时会传递给目标服务的文档摘要) |
discover.excluded | 排除目标服务名 |
discover.included | 包括目标服务名 |
routes | 是一个 Map<String, DocDocket> 结构,用于配置文档路由(即,手动配置文档) |
discover 配置,会自动生成服务相关的 DocDocket 及对应的 upstream,其中服务名会成为 upstream.service 和 upstream.contextPath,uriPattern 会生成 upstream.uri。
- discover,只会发现有请求到的服务(即,LoadBalance.get(name) 触发到的服务)
- 没有触发到的服务,可以通过 "included" 进行配置
4、聚合示例
(1)模块服务 app-api (当它是 22 个服务中的某个了)
yaml
solon.app:
namespace: test
group: demo
name: app-api
solon.cloud.nacos:
server: "127.0.0.1:8848" #nacos服务地址
solon.docs: #配置本地文档接口服务
routes:
default: #使用固定文档组名(更方便聚合)
groupName: "app端接口"
apis:
- basePackage: "com.demo.controller.app"
(2)文档网关服务 doc-gateway (有两种配置方式)
使用发现服务配置(这个简单,可自动和批量)
yml
solon.app:
namespace: test
group: demo
name: doc-gateway
solon.cloud.nacos:
server: "127.0.0.1:8848" #nacos服务地址
solon.docs:
discover:
uriPattern: "swagger/v2?group=default"
included:
- "app-api" #具体的功能服务名
或者,手动本置(routes, discover 配置,也可以同时使用)
yml
solon.app:
namespace: test
group: demo
name: doc-gateway
solon.cloud.nacos:
server: "127.0.0.1:8848" #nacos服务地址
solon.docs:
routes:
appApi: # doc group-id
groupName: "app端接口" # doc group-name
upstream:
service: "app-api" #使用具体地址,或使用服务名
contextPath: "/app-api" #可选(没有时,根据 service 自动生成)
uri: "swagger/v2?group=default"
更多内容,可参考 Solon 官网。