Dubbo 版 Swagger 来啦!Dubbo-Api-Docs 发布
Posted 阿里巴巴云原生
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Dubbo 版 Swagger 来啦!Dubbo-Api-Docs 发布相关的知识,希望对你有一定的参考价值。
作者 | 柯然(邪影)
背景
Dubbo 这边有没有集合文档展示和测试功能,可以不用写文档就能把接口直接给调用方,类似 Swagger/Springfox 的工具呢?
-
有些是基于 Springfox 做的,直接一个文本域放 JSON,与目前 Admin 中的测试功能大同小异。
-
有些是直接基于 Swagger 的 Java 版 OpenApI 规范生成工具做的,能把一些基础数据类型的简单参数作为表单项展示。
但也有非 web 的提供者,为了文档我得把它变为 web 项目吗?(还要引入一堆 Web 框架的依赖?比如 Spring MVC?)或者说生产环境打包时,删除它的引用和代码里的相关注解? 有没有简单点的方式呢?
-
提供一些描述接口信息的简单注解。
-
在提供者启动时解析注解并缓存解析结果。
-
在提供者增加几个 Dubbo-Api-Docs 使用的获取接口信息的接口。
-
在 Dubbo Admin 侧通过 Dubbo 泛化调用实现 Http 方式调用 Dubbo 接口的网关。
-
在 Dubbo Admin 侧实现接口信息展示和调用接口功能。 -
下列情况中的参数直接展示为表单项,其他的展示为 JSON。
-
方法参数为基础数据类型的 -
方法参数为一个 Bean,Bena 中属性为基础数据类型的
-
很少的第三方依赖,甚至大部分都是你项目里本身就使用的。 -
可以通过 profile 决定是否加载,打包时简单地修改 profile 就能区分生产和测试,甚至 profile 你本来就使用了。
今天,我很高兴的宣布:Dubbo 用户也可以享受类似 Swagger 的体验了 -- Dubbo-Api-Docs 发布了。
简介
在 dubbo 项目引入 Dubbo-Api-Docs 相关 jar 包,并增加类似 Swagger 的注解。
在 Dubbo-Admin 中查看接口描述并测试。
当前版本: 2.7.8.1
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-api-docs-annotations</artifactId>
<version>${dubbo-version}</version>
</dependency>
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-api-docs-core</artifactId>
<version>${dubbo-version}</version>
</dependency>
快速入门
1. dubbo 提供者项目的方法参数中加上 Dubbo-Api-Docs 注解
-
如果 dubbo 提供者的接口和方法参数在一个单独的 jar 项目中,则在该项目中引入: dubbo-api-docs-annotations。 -
dubbo 提供者项目引入 dubbo-api-docs-core。 -
在提供者项目的项目启动类(标注了 @SpringBootApplication 的类),或者配制类(标注了 @Configuration 的类)中增加注解 @EnableDubboApiDocs,以启用 Dubbo Api Docs 功能。
为避免增加生产环境中的资源占用,建议单独创建一个配制类用于启用 Dubbo-Api-Docs,并配合 @Profile("dev") 注解使用。
当然,Dubbo-Api-Docs 仅在项目启动时多消耗了点 CPU 资源,并使用了一点点内存用于缓存,将来会考虑将缓存中的内容放到元数据中心。
下面以 项目中的部分服务接口为例:
git clone -b 2.7.x https://github.com/apache/dubbo-spi-extensions.git
-
examples-api:一个 jar 包项目,其中包含服务的接口和接口参数 Bean。 -
examples-provider:提供者服务端,包含 spring boot 启动器和服务的实现。
examples-api:
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-api-docs-annotations</artifactId>
<version>2.7.8</version>
</dependency>
-
QuickStartRequestBean 作为参数 Bean,添加 @RequestParam。
public class QuickStartRequestBean {
"You name", required = true, description = "please enter your full name", example = "Zhang San") (value =
private String name;
"You age", defaultValue = "18") (value =
private int age;
"Are you a main?") (
private boolean man;
// getter/setter略...
}
-
QuickStartRespBean 作为响应 Bean,添加 @ResponseProperty。
public class QuickStartRespBean {
private int code;
private String msg;
// getter/setter略...
}
examples-provider:
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-api-docs-core</artifactId>
<version>2.7.8</version>
</dependency>
-
在 QuickStartDemoImpl 中:
"quick start demo", apiInterface = IQuickStartDemo.class, version = "v0.1") (value =
public class QuickStartDemoImpl implements IQuickStartDemo {
"quick start demo", version = "v0.1", description = "this api is a quick start demo", responseClassDescription="A quick start response bean") (value =
public QuickStartRespBean quickStart(@RequestParam(value = "strParam", required = true) String strParam, QuickStartRequestBean beanParam) {
return new QuickStartRespBean(200, "hello " + beanParam.getName() + ", " + beanParam.toString());
}
}
// 配合 Profile 一起使用, 在 profile 为 dev 时才会加载该配制类
// 开启 Dubbo-Api-Docs
public class DubboDocConfig {
}
中有更多更为详尽的例子,下文中有注解的详细说明。下面我们来看一下增加 Dubbo-Api-Docs 后的效果图:
2. 启动提供者项目
-
示例使用 nacos 作为注册中心, 在上面的例子中,我们启动 examples-provider 项目中的 org.apache.dubbo.apidocs.examples.ExampleApplication。
mvn spring-boot:run
3. 下载 dubbo-admin
dubbo-admin 需要下载 develop 分支源码启动。
git clone -b develop https://github.com/apache/dubbo-admin.git
4. 启动访问 dubbo-admin
1. 在 dubbo-admin-server/src/main/resources/application.properties 中修改注册中心地址
2. 编译 mvn clean package
3. 启动:
mvn --projects dubbo-admin-server spring-boot:run
或者
cd dubbo-admin-distribution/target; java -jar dubbo-admin-0.1.jar
4. 浏览器访问: http://localhost:8080
5. 默认帐号密码都是: root
5. 进入"接口文档"模块
-
在 “dubbo 提供者 IP” 和 “dubbo提供者端口” 中分别输入提供者所在机器 IP 和端口,点击右侧 “加载接口列表” 按钮。
-
左侧接口列表中加载出接口列表,点击任意接口,右边展示出该接口信息及参数表单。
-
填入表单内容后,点击最下方测试按钮。
-
响应部分展示了响应示例及实际响应结果。
源码仓库
1. dubbo-spi-extensions
该仓库存放 dubbo 的一些非核心功能的扩展,Dubbo-Api-Docs 作为该仓库中的一个子模块,由于该仓库属于 Dubbo 3.0 中规划的一部分,而 Dubbo-Api-Docs 是基于 Dubbo 2.7.x 开发的,所以在该仓库中增加了,Dubbo-Api-Docs 就在该分支下。
-
dubbo-api-docs-annotations:文档生成的相关注解。考虑到实际情况中 dubbo api 的接口类和接口参数会规划为一个单独的 jar 包,所以注解也独立为一个 jar 包。本文后面会对注解做详细说明。
-
dubbo-api-docs-core:负责解析注解,生成文档信息并缓存。前面提到的 Dubbo-Api-Docs 相关接口也在该包中。
-
dubbo-api-docs-examples:使用示例。
2. Dubbo-Admin
注解说明
-
@EnableDubboApiDocs:配制注解,启用 dubbo api docs 功能。
-
@ApiModule:类注解,dubbo 接口模块信息,用于标注一个接口类模块的用途。
-
value:模块名称 -
apiInterface:提供者实现的接口 -
version:模块版本 -
-
@ApiDoc:方法注解,dubbo 接口信息,用于标注一个接口的用途。
-
value:接口名称 -
description:接口描述(可使用 html 标签) -
version:接口版本 -
responseClassDescription:响应的数据的描述 -
-
@RequestParam:类属性/方法参数注解,标注请求参数。
-
value:参数名 -
required:是否必传参数 -
description:参数描述 -
example:参数示例 -
defaultValue:参数默认值 -
allowableValues:允许的值,设置该属性后界面上将对参数生成下拉列表 -
注:使用该属性后将生成下拉选择框 -
boolean 类型的参数不用设置该属性,将默认生成 true/false 的下拉列表 -
枚举类型的参数会自动生成下拉列表,如果不想开放全部的枚举值,可以单独设置此属性 -
-
@ResponseProperty:类属性注解,标注响应参数。
-
value:参数名 -
example:示例
使用注意
-
响应 bean(接口的返回类型)支持自定义泛型,但只支持一个泛型占位符。 -
关于 Map 的使用:Map 的 key 只能用基本数据类型。如果 Map 的 key 不是基础数据类型,生成的就不是标准 json 格式,会出异常。 -
接口的同步/异步取自 org.apache.dubbo.config.annotation.Service#async / org.apache.dubbo.config.annotation.DubboService#async。
示例说明
中的 dubbo-api-docs-examples 目录中为示例工程:
-
examples-api:jar 包项目,包含服务提供者的接口类及参数 Bean。
-
examples-provider:使用 dubbo-spring-boot-starter 的提供者项目,注册中心使用 nacos。
-
examples-provider-sca:使用 spring-cloud-starter-dubbo 的提供者项目,注册中心使用 nacos。
示例使用步骤
示例使用 nacos 作为注册中心,
任意启动 examples-provider 和 examples-provider-sca 中的任意一个,当然也可以两个都启动。examples-provider 使用 20881 端口 examples-provider-sca 使用 20882 端口。两个项目都是 spring boot 项目,启动类在 org.apache.dubbo.apidocs.examples 包下。
启动,浏览器访问:。
进入 dubbo-admin 中的 “接口文档” 模块。
在 “dubbo 提供者 IP” 和 “dubbo 提供者端口” 中分别输入提供者所在机器 IP 和端口,点击右侧 “加载接口列表” 按钮。
左侧接口列表中加载出接口列表,点击任意接口,右边展示出该接口信息及参数表单。
填入表单内容后,点击最下方测试按钮。
响应部分展示了响应示例及实际响应结果。
如果你对 Dubbo Api Docs 的建设有兴趣,欢迎你加入 Dubbo Api Docs 共建小组:
也欢迎你加入 Dubbo 开源讨论群:
以上是关于Dubbo 版 Swagger 来啦!Dubbo-Api-Docs 发布的主要内容,如果未能解决你的问题,请参考以下文章