使用 Apifox、Postman 测试 Dubbo 服务，Apache Dubbo OpenAPI 即将发布

作者：何亮，Apache Dubbo Contributor

Apache Dubbo OpenAPI 简介

设计背景

在微服务体系中，RPC 服务的文档管理、测试、调用协作一直都是影响研发效能的关键一环，这些难题通常是由于 RPC 的特性所决定的：RPC 服务的定义方式、RPC 协议格式不一，缺少放之宇宙而皆准的统一规范。长期以来，Apache Dubbo 的开发者们也面临同样问题的困扰。

随着 Apache Dubbo 3.3.3 版本进入发布周期（未来1个月内），Dubbo 推出了完全兼容 Swagger OpenAPI 3 规范的 API 管理功能，让用户的 RPC 服务可以方便地生成 OpenAPI 格式文档，从而实现标准化的服务管理。Dubbo OpenAPI 机制的发布，带来了 RPC 服务 API 管理的最佳实践，它从很大程度上解决了 RPC API 管理的问题：

1）减少引入额外依赖和配置： Dubbo 3.3.3 提供内置的 OpenAPI 文档生成功能，用户无需引入额外的第三方工具或复杂的配置即可完成所有操作，降低了学习和使用成本。

2）兼容 REST 协议的卓越能力： 一般的 RPC 服务在兼容 REST 协议时会遇到较大困难，导致 OpenAPI 文档生成较为麻烦。而 Dubbo 3.3.3 基于 Triple 协议的先天优势，实现了对 REST 的无缝支持，极大地提升了 OpenAPI 文档生成和集成的效果。

3）减少手动文档编写工作量： 以前用户需要手动书写 OpenAPI 文档，工作量大且容易出错，现在只需简单配置即可生成。

4）保证文档与代码同步一致： 手写文档往往会滞后于代码更新，而 Dubbo 自动生成文档可以确保接口定义和文档始终一致。

5）跨语言支持更强大： 新增的 Proto 格式导出能力，让多语言开发团队可以更方便地共享接口定义，降低语言间通信的复杂性。

核心功能

以下是 Apache Dubbo OpenAPI 提供的核心功能特性。

1）自动生成 OpenAPI 文档： 无需手动编写接口文档，Dubbo 直接从接口定义中生成 OpenAPI 文档。

2）支持 Proto 格式导出： 除了常见的 JSON、YAML 格式外，Dubbo 3.3.3 新增了 Proto 格式导出功能。通过这一特性，用户可以直接将接口定义转换为 Protocol Buffers 文件，方便在多语言场景下使用，提高跨语言调用的便利性。

3）与 Swagger 完美集成： Dubbo 3.3.3 自带与 Swagger 的无缝集成，服务启动后访问默认的 URL 即可打开 Swagger UI 的 HTML 页面，快速查看和测试接口。

4）实时同步更新： 服务更新后，OpenAPI 文档可以自动同步更新，保证接口文档与代码的实时一致性。

5）快速导入到 Apifox 等工具： 生成的 OpenAPI 文档可以一键导入到 Apifox 中，用于接口调试、测试和 Mock 数据生成。

一键生成 OpenAPI，完美集成 Apifox

接下来，我们将详细讲解 Apache Dubbo OpenAPI 的使用方式。并以服务测试为例，演示如何使用 Apifox 快速测试 Apache Dubbo 服务。

基础功能演示

第一步：引入 Maven 依赖

在项目的 pom.xml 文件中添加以下依赖：

 <dependency>
      <groupId>org.apache.dubbo</groupId>
      <artifactId>dubbo-rest-openapi</artifactId>
      <version>3.3.3</version>
</dependency>

第二步：配置 Dubbo 生成 OpenAPI 文档

在 application.yaml 文件中修改相关配置：只需要打开 rest - openapi - enabled 即可。

dubbo:
  application:
    name: ${spring.application.name}
    qos-enable: false
  protocol:
    name: tri
    port: 50052
    triple:
      rest:
        openapi:
          enabled: true

第三步：访问 OpenAPI 规范文档

1. 访问 Swagger UI

启动 Dubbo 进程后，通过访问 http://<主机>:<端口>/dubbo/openapi 可打开内置的 Swagger UI 界面。如本示例中，我们可通过 http:/127.0.0.1:50052/dubbo/openapi 在本地访问，效果图如下：

2. 访问 OpenAPI 文档（通过此方法获得 OpenAPI 后即可导入 Apifox 中）：在 Dubbo 进程启动后，通过访问 http://<主机>:<端口>/dubbo/openapi/api-docs 可以生成 OpenAPI 规范的服务 API 定义文档。

除了 JSON 格式之外，还支持生成 YAML、Proto 格式文档：

访问 http://<主机>:<端口>/dubbo/openapi/api-docs.yaml 生成 YAML 格式文档。
访问 http://<主机>:<端口>/dubbo/openapi/api-docs.proto 生成 YAML 格式文档。

高级配置示例

通过注解定制 OpenAPI 文档

用户可以根据现有的服务接口增加注解，以丰富或定制生成的 OpenAPI 文档。目前 Dubbo 提供了三个内置注解，分别是 @OpenAPI、@Schema 和 @Operation（在 package org.apache.dubbo.remoting.http12.rest 下），用于快速生成和定制化 OpenAPI 文档：

1. @OpenAPI

功能： 定义服务接口的全局信息，如标题、描述、版本、分组和标签等。
用途： 为服务提供整体的 OpenAPI 配置，使文档更具描述性。
示例：

@OpenAPI(
    infoTitle = "Dubbo OpenAPI",
    infoDescription = "This API provides greeting services for users.",
    infoVersion = "v1",
    docDescription = "API for greeting users with their names and titles."
)
public class DemoServiceImpl implements DemoService {
    // 服务方法
}

2. @Operation

功能： 为具体的服务方法定义操作信息，如 HTTP 方法、摘要、描述、版本和标签等。
用途： 针对方法级别的 OpenAPI 定义，使文档描述更加详细和可操作。
示例：

@Operation(description = "Returns a greeting message with the provided name.")
@Override
public String hello(@Schema(description = "Name of the person to greet") String name) {
    return "Hello " + name;
}

3. @Schema

功能： 定义参数、字段或数据模型的详细元信息，如类型、格式、描述、默认值和枚举等。
用途： 为请求和响应中的数据结构提供详细描述，使文档更加直观规范。
示例：

@Schema(title = "用户模型", description = "表示用户信息的对象")
public class User {
    @Schema(title = "用户名", example = "Tom")
    private String name;
}

通过这些注解，开发者可以快速生成基础文档，也能根据需求实现高度定制化。如果场景较为简单，可优先选择 Dubbo 内置的注解；在复杂场景下，可结合 Swagger 提供的注解进一步增强功能（在 package io.swagger.v3.oas.annotations.media 下）。

过滤服务列表，生成 OpenAPI 文档

在生成 OpenAPI 文档过程中，我们可以结合以上注解属性，过滤和定制生成的文档内容。以下是几种常用的文档过滤功能：

按分组， 通过访问 http://<主机>:<端口>/dubbo/openapi/api-docs/{group} 实现。
按版本， 通过访问 http://<主机>:<端口>/dubbo/openapi/api-docs?version=1.0.0 实现。
按标签， 通过访问 http://<主机>:<端口>/dubbo/openapi/api-docs?tag=user,order 实现。

总结

Apache Dubbo 3.3.3（即将发布）实现了与 OpenAPI 的深度集成，通过与 OpenAPI 的深度集成，用户能够体验到从文档生成到接口调试、测试和优化的全流程自动化支持。不论是减少手动工作量、提升开发效率，还是支持多语言和多环境，Dubbo 3.3.3 都展现了其对开发者体验的极大关注。结合强大的 Mock 数据生成和自动化测试能力，这一版本为开发者提供了极具竞争力的服务治理解决方案。如果你正在寻找高效、易用的微服务框架，Dubbo 3.3.3 将是你不容错过的选择。

示例链接：https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-triple-rest