Apache Dubbo OpenAPI 简介
Cloud Native
在微服务体系中，RPC 服务的文档管理、测试、调用协作一直都是影响研发效能的关键一环，这些难题通常是由于 RPC 的特性所决定的：RPC 服务的定义方式、RPC 协议格式不一，缺少放之宇宙而皆准的统一规范。长期以来，Apache 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
Cloud Native
接下来，我们将详细讲解 Apache Dubbo OpenAPI 的使用方式。并以服务测试为例，演示如何使用 Apifox 快速测试 Apache Dubbo 服务。
第一步：引入 Maven 依赖
<dependency><groupId>org.apache.dubbo</groupId><artifactId>dubbo-rest-openapi</artifactId><version>3.3.3</version></dependency>
第二步：配置 Dubbo 生成 OpenAPI 文档
dubbo:application:name: ${spring.application.name}qos-enable: falseprotocol:name: triport: 50052triple:rest:openapi:enabled: true
第三步：访问 OpenAPI 规范文档
访问 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.")@Overridepublic 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;}
过滤服务列表，生成 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 实现。
总结
Cloud Native
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
