使用 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 文件中添加以下依靠：

1. <dependency>
2.       <groupId>org.apache.dubbo</groupId>
3.       <artifactId>dubbo-rest-openapi</artifactId>
4.       <version>3.3.3</version>
5. </dependency>

复制代码

第二步：设置 Dubbo 天生 OpenAPI 文档

在 application.yaml 文件中修改相干设置：只必要打开 rest - openapi - enabled 即可。

1. dubbo:
2.   application:
3.     name: ${spring.application.name}
4.     qos-enable: false
5.   protocol:
6.     name: tri
7.     port: 50052
8.     triple:
9.       rest:
10.         openapi:
11.           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 设置，使文档更具形貌性。
  
• 示例：
  

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

复制代码

2. @Operation

• 功能： 为详细的服务方法界说操纵信息，如 HTTP 方法、择要、形貌、版本和标签等。
  
• 用途： 针对方法级别的 OpenAPI 界说，使文档形貌更加详细和可操纵。
  
• 示例：
  

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

复制代码

3. @Schema

• 功能： 界说参数、字段或数据模子的详细元信息，如范例、格式、形貌、默认值和罗列等。
  
• 用途： 为哀求和相应中的数据布局提供详细形貌，使文档更加直观规范。
  
• 示例：
  

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

复制代码

通过这些注解，开发者可以快速天生根本文档，也能根据需求实现高度定制化。假如场景较为简朴，可优先选择 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

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。