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

本文涉及的产品
任务调度 XXL-JOB 版免费试用,400 元额度,开发版规格
Serverless 应用引擎免费试用套餐包,4320000 CU,有效期3个月
云原生网关 MSE Higress,422元/月
简介: Apache Dubbo 3.3.3(即将发布)实现了与 OpenAPI 的深度集成,通过与 OpenAPI 的深度集成,用户能够体验到从文档生成到接口调试、测试和优化的全流程自动化支持。不论是减少手动工作量、提升开发效率,还是支持多语言和多环境,Dubbo 3.3.3 都展现了其对开发者体验的极大关注。结合强大的 Mock 数据生成和自动化测试能力,这一版本为开发者提供了极具竞争力的服务治理解决方案。如果你正在寻找高效、易用的微服务框架,Dubbo 3.3.3 将是你不容错过的选择。

作者:何亮,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 在本地访问,效果图如下:

image.png

2. 访问 OpenAPI 文档(通过此方法获得 OpenAPI 后即可导入 Apifox 中):

在 Dubbo 进程启动后,通过访问 http://<主机>:<端口>/dubbo/openapi/api-docs 可以生成 OpenAPI 规范的服务 API 定义文档。

image.png

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

相关实践学习
基于MSE实现微服务的全链路灰度
通过本场景的实验操作,您将了解并实现在线业务的微服务全链路灰度能力。
相关文章
|
1月前
|
数据可视化 前端开发 测试技术
接口测试新选择:Postman替代方案全解析
在软件开发中,接口测试工具至关重要。Postman长期占据主导地位,但随着国产工具的崛起,越来越多开发者转向更适合中国市场的替代方案——Apifox。它不仅支持中英文切换、完全免费不限人数,还具备强大的可视化操作、自动生成文档和API调试功能,极大简化了开发流程。
|
4天前
|
JSON 前端开发 测试技术
大前端之前端开发接口测试工具postman的使用方法-简单get接口请求测试的使用方法-简单教学一看就会-以实际例子来说明-优雅草卓伊凡
大前端之前端开发接口测试工具postman的使用方法-简单get接口请求测试的使用方法-简单教学一看就会-以实际例子来说明-优雅草卓伊凡
41 10
大前端之前端开发接口测试工具postman的使用方法-简单get接口请求测试的使用方法-简单教学一看就会-以实际例子来说明-优雅草卓伊凡
|
2天前
|
JSON 前端开发 API
以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
23 5
以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
|
4月前
|
存储 缓存 算法
分布式锁服务深度解析:以Apache Flink的Checkpointing机制为例
【10月更文挑战第7天】在分布式系统中,多个进程或节点可能需要同时访问和操作共享资源。为了确保数据的一致性和系统的稳定性,我们需要一种机制来协调这些进程或节点的访问,避免并发冲突和竞态条件。分布式锁服务正是为此而生的一种解决方案。它通过在网络环境中实现锁机制,确保同一时间只有一个进程或节点能够访问和操作共享资源。
172 3
|
4月前
|
Linux 网络安全 Apache
CentOS 7.2配置Apache服务httpd(上)
CentOS 7.2配置Apache服务httpd(上)
381 1
|
3月前
|
JSON Java 测试技术
SpringCloud2023实战之接口服务测试工具SpringBootTest
SpringBootTest同时集成了JUnit Jupiter、AssertJ、Hamcrest测试辅助库,使得更容易编写但愿测试代码。
92 3
|
4月前
|
存储 分布式计算 druid
大数据-155 Apache Druid 架构与原理详解 数据存储 索引服务 压缩机制
大数据-155 Apache Druid 架构与原理详解 数据存储 索引服务 压缩机制
108 3
|
4月前
|
监控 Dubbo Java
dubbo学习三:springboot整合dubbo+zookeeper,并使用dubbo管理界面监控服务是否注册到zookeeper上。
这篇文章详细介绍了如何将Spring Boot与Dubbo和Zookeeper整合,并通过Dubbo管理界面监控服务注册情况。
286 0
dubbo学习三:springboot整合dubbo+zookeeper,并使用dubbo管理界面监控服务是否注册到zookeeper上。
|
4月前
|
Linux PHP Apache
CentOS 7.2配置Apache服务httpd(下)
CentOS 7.2配置Apache服务httpd(下)
70 1
|
6月前
|
C# 开发者 Windows
勇敢迈出第一步:手把手教你如何在WPF开源项目中贡献你的第一行代码,从选择项目到提交PR的全过程解析与实战技巧分享
【8月更文挑战第31天】本文指导您如何在Windows Presentation Foundation(WPF)相关的开源项目中贡献代码。无论您是初学者还是有经验的开发者,参与这类项目都能加深对WPF框架的理解并拓展职业履历。文章推荐了一些适合入门的项目如MvvmLight和MahApps.Metro,并详细介绍了从选择项目、设置开发环境到提交代码的全过程。通过具体示例,如添加按钮点击事件处理程序,帮助您迈出第一步。此外,还强调了提交Pull Request时保持专业沟通的重要性。参与开源不仅能提升技能,还能促进社区交流。
67 0

推荐镜像

更多