关于java:Dubbo-版-Swagger-来啦DubboApiDocs-发布

作者 | 柯然（邪影）
起源 | 阿里巴巴云原生公众号

Swagger 是一个标准和残缺的前端框架，用于生成、形容、调用和可视化 RESTful 格调的 Web 服务。Swagger 标准也逐步倒退成为了 OpenAPI 标准。

Springfox 是一个集成了 Swagger，基于 Sring MVC/Spring Webflux 实现的一个 Swagger 形容文件生成框架，通过应用它定义的一些形容接口的注解主动生成 Swagger 的形容文件，使 Swagger 可能展现并调用接口。

置信很多人都据说和应用过 Swagger 和 Springfox，这里就不再赘述了。

Dubbo-Admin 中有接口测试性能，然而短少接口形容的文档，所以该测试性能比拟适宜接口开发人员用于测试接口。而其他人想要应用该性能就必须先通过接口开发者编写的文档或者其余形式，理解分明接口信息能力应用该功能测试接口。

Dubbo 这边有没有汇合文档展现和测试性能，能够不必写文档就能把接口间接给调用方，相似 Swagger/Springfox 的工具呢？

之前做过一些调研，找到一些相似的工具：

有些是基于 Springfox 做的，间接一个文本域放 JSON，与目前 Admin 中的测试性能大同小异。
有些是间接基于 Swagger 的 Java 版 OpenApI 标准生成工具做的，能把一些根底数据类型的简略参数作为表单项展现。

它们都有一个共同点：会把你的提供者变为 Web 我的项目。当然有些提供者是通过 web 容器加载启动的，甚至也有和 web 工程在一起的，那就无所谓了。

但也有非 web 的提供者，为了文档我得把它变为 web 我的项目吗?（还要引入一堆 Web 框架的依赖？比方 Spring MVC？）或者说生产环境打包时，删除它的援用和代码里的相干注解? 有没有简略点的形式呢?

OpenAPI 中没有 RPC 的标准，Swagger 是 OpenAPI 的实现，所以也不反对 RPC 相干调用。Springfox 是通过 Swagger 实现的 RESTful API 的工具，而 RESTful 又是基于 Web 的，Dubbo 没法间接应用。咱们最终抉择了本人实现：

提供一些形容接口信息的简略注解。
在提供者启动时解析注解并缓存解析后果。
在提供者减少几个 Dubbo-Api-Docs 应用的获取接口信息的接口。
在 Dubbo Admin 侧通过 Dubbo 泛化调用实现 Http 形式调用 Dubbo 接口的网关。
在 Dubbo Admin 侧实现接口信息展现和调用接口性能。
下列状况中的参数间接展现为表单项，其余的展现为 JSON。
- 办法参数为根底数据类型的
- 办法参数为一个 Bean，Bena 中属性为根底数据类型的
很少的第三方依赖，甚至大部分都是你我的项目里自身就应用的。
能够通过 profile 决定是否加载，打包时简略地批改 profile 就能辨别生产和测试，甚至 profile 你原本就应用了。

明天，我很快乐的发表：Dubbo 用户也能够享受相似 Swagger 的体验了 — Dubbo-Api-Docs 公布了。

Dubbo-Api-Docs 是一个展现 dubbo 接口文档，测试接口的工具。

应用 Dubbo-Api-Docs 分为两个次要步骤：

在 dubbo 我的项目引入 Dubbo-Api-Docs 相干 jar 包，并减少相似 Swagger 的注解。
在 Dubbo-Admin 中查看接口形容并测试。

通过以上两个步骤，即可享受相似 Swagger 的体验，并且能够在生产环境中敞开 Dubbo-Api-Docs 的扫描。

Dubbo-Api-Docs 目前通过直连服务节点的形式获取该服务的接口列表。测试接口时，能够直连也能够通过注册核心，将来会减少通过注册核心获取服务列表的形式，并依据 Dubbo 的降级布局减少新的性能反对，也会依据社区的需要减少性能。

Dubbo-Api-Docs 会在服务提供者启动结束后，扫描 docs 相干注解并将处理结果缓存，并减少一些 Dubbo-Api-Docs 相干的 Dubbo 提供者接口。缓存的数据在未来可能会放到 Dubbo 元数据中心中。

<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>

如果 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

进入 dubbo-spi-extensions/dubbo-api-docs/dubbo-api-docs-examples 目录。

dubbo-api-docs-examples 中有两个子模块：

examples-api：一个 jar 包我的项目，其中蕴含服务的接口和接口参数 Bean。
examples-provider：提供者服务端，蕴含 spring boot 启动器和服务的实现。

上面咱们在这两个子模块中减少 Dubbo-Api-Docs：

examples-api:

maven 引入:

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-annotations</artifactId>
    <version>2.7.8</version>
</dependency>

org.apache.dubbo.apidocs.examples.params 中有两个 Bean，咱们来为它们增加 docs 注解。

QuickStartRequestBean 作为参数 Bean，增加 @RequestParam。

public class QuickStartRequestBean {@RequestParam(value = "You name", required = true, description = "please enter your full name", example = "Zhang San")
  private String name;

  @RequestParam(value = "You age", defaultValue = "18")
  private int age;

  @RequestParam("Are you a main?")
  private boolean man;
  
  // getter/setter 略...
}

QuickStartRespBean 作为响应 Bean，增加 @ResponseProperty。

public class QuickStartRespBean {@ResponseProperty(value = "Response code", example = "500")
  private int code;

  @ResponseProperty("Response message")
  private String msg;

  // getter/setter 略...
}

因为咱们只筛选了局部接口作为演示，到此这些接口波及的 docs 注解增加结束。

examples-provider:

maven 引入：

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-core</artifactId>
    <version>2.7.8</version>
</dependency>

咱们筛选一个接口作为演示：

org.apache.dubbo.apidocs.examples.api.impl.QuickStartDemoImpl 中的 quickStart 办法。

QuickStartDemoImpl 实现了 api 包中的 org.apache.dubbo.apidocs.examples.api.IQuickStartDemo 接口。

在 QuickStartDemoImpl 中:

@DubboService
@ApiModule(value = "quick start demo", apiInterface = IQuickStartDemo.class, version = "v0.1")
public class QuickStartDemoImpl implements IQuickStartDemo {@ApiDoc(value = "quick start demo", version = "v0.1", description = "this api is a quick start demo", responseClassDescription="A quick start response bean")
  @Override
  public QuickStartRespBean quickStart(@RequestParam(value = "strParam", required = true) String strParam, QuickStartRequestBean beanParam) {return new QuickStartRespBean(200, "hello" + beanParam.getName() + "," + beanParam.toString());
  }
}

到此 docs 相干注解已增加结束，上面咱们来开启 Dubbo-Api-Docs。新增一个配制类，地位任意，只有能被 spring boot 扫描到就行。

咱们在 org.apache.dubbo.apidocs.examples.cfg 包中新增一个配制类 DubboDocConfig：

@Configuration
@Profile("dev")  // 配合 Profile 一起应用, 在 profile 为 dev 时才会加载该配制类
@EnableDubboApiDocs  // 开启 Dubbo-Api-Docs
public class DubboDocConfig {}

到此 Dubbo-Api-Docs 相干的货色曾经增加结束。

dubbo-api-docs-examples 中有更多更为详尽的例子，下文中有注解的具体阐明。上面咱们来看一下减少 Dubbo-Api-Docs 后的效果图：

示例应用 nacos 作为注册核心，下载并启动 nacos。
在下面的例子中，咱们启动 examples-provider 我的项目中的 org.apache.dubbo.apidocs.examples.ExampleApplication。

在 examples-provider 目录中：

mvn spring-boot:run

dubbo-admin 须要下载 develop 分支源码启动。

git clone -b develop https://github.com/apache/dubbo-admin.git

参考 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

在“dubbo 提供者 IP”和“dubbo 提供者端口”中别离输出提供者所在机器 IP 和端口，点击右侧“加载接口列表”按钮。
左侧接口列表中加载出接口列表, 点击任意接口，左边展现出该接口信息及参数表单。
填入表单内容后，点击最下方测试按钮。
响应局部展现了响应示例及理论响应后果。

Dubbo-Api-Docs 依据性能拆分，别离在两个仓库中：

dubbo-spi-extensions 仓库地址

该仓库寄存 dubbo 的一些非核心性能的扩大，Dubbo-Api-Docs 作为该仓库中的一个子模块，因为该仓库属于 Dubbo 3.0 中布局的一部分，而 Dubbo-Api-Docs 是基于 Dubbo 2.7.x 开发的，所以在该仓库中减少了 2.7.x 分支，Dubbo-Api-Docs 就在该分支下。

该仓库中蕴含了 Dubbo-Api-Docs 的文档相干注解、注解扫描能力和应用示例：

dubbo-api-docs-annotations：文档生成的相干注解。思考到理论状况中 dubbo api 的接口类和接口参数会布局为一个独自的 jar 包，所以注解也独立为一个 jar 包。本文前面会对注解做具体阐明。
dubbo-api-docs-core：负责解析注解，生成文档信息并缓存。后面提到的 Dubbo-Api-Docs 相干接口也在该包中。
dubbo-api-docs-examples：应用示例。

Dubbo-Admin 仓库地址

文档的展现及测试放在了 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。

examples-api：jar 包我的项目，蕴含服务提供者的接口类及参数 Bean。
examples-provider：应用 dubbo-spring-boot-starter 的提供者我的项目，注册核心应用 nacos。
examples-provider-sca：应用 spring-cloud-starter-dubbo 的提供者我的项目，注册核心应用 nacos。

示例应用 nacos 作为注册核心，下载并启动 nacos。
任意启动 examples-provider 和 examples-provider-sca 中的任意一个，当然也能够两个都启动。examples-provider 应用 20881 端口 examples-provider-sca 应用 20882 端口。两个我的项目都是 spring boot 我的项目，启动类在 org.apache.dubbo.apidocs.examples 包下。
启动 Dubbo-Admin，浏览器拜访：http://localhost:8080。
进入 dubbo-admin 中的“接口文档”模块。
在“dubbo 提供者 IP”和“dubbo 提供者端口”中别离输出提供者所在机器 IP 和端口，点击右侧“加载接口列表”按钮。
左侧接口列表中加载出接口列表，点击任意接口，左边展现出该接口信息及参数表单。
填入表单内容后，点击最下方测试按钮。
响应局部展现了响应示例及理论响应后果。

如果你对 Dubbo Api Docs 的建设有趣味，欢送你钉钉搜寻群号：34403965，退出 Dubbo Api Docs 共建小组；也欢送你钉钉搜寻群号：21976540，退出 Dubbo 开源探讨群。

关于java:Dubbo-版-Swagger-来啦DubboApiDocs-发布

背景

简介

以后版本: 2.7.8.1

疾速入门

1. dubbo 提供者我的项目的办法参数中加上 Dubbo-Api-Docs 注解

上面以 dubbo-api-docs-examples 我的项目中的局部服务接口为例：

2. 启动提供者我的项目

3. 下载 dubbo-admin

dubbo-admin 仓库

4. 启动拜访 dubbo-admin

5. 进入 ” 接口文档 ” 模块

源码仓库

1. dubbo-spi-extensions

dubbo-spi-extensions 仓库地址

2. Dubbo-Admin

Dubbo-Admin 仓库地址

注解阐明

应用留神

示例阐明

dubbo-spi-extensions / Dubbo-Api-Docs 中的 dubbo-api-docs-examples 目录中为示例工程：

示例应用步骤

Just My Socks（注册教程内含优惠码）

关于java:Dubbo-版-Swagger-来啦DubboApiDocs-发布

背景

简介

以后版本: 2.7.8.1

疾速入门

1. dubbo 提供者我的项目的办法参数中加上 Dubbo-Api-Docs 注解

上面以 dubbo-api-docs-examples 我的项目中的局部服务接口为例：

2. 启动提供者我的项目

3. 下载 dubbo-admin

dubbo-admin 仓库

4. 启动拜访 dubbo-admin

5. 进入 ” 接口文档 ” 模块

源码仓库

1. dubbo-spi-extensions

dubbo-spi-extensions 仓库地址

2. Dubbo-Admin

Dubbo-Admin 仓库地址

注解阐明

应用留神

示例阐明

dubbo-spi-extensions / Dubbo-Api-Docs 中的 dubbo-api-docs-examples 目录中为示例工程：

示例应用步骤

Just My Socks（注册教程 内含优惠码）

Just My Socks（注册教程内含优惠码）