Swagger 自动生成 Dubbo 服务的接口文档,以及测试调用

news2024/11/11 13:15:54

1. 概述

在使用 SpringMVC 构建 HTTP API 时,我们可以通过 Swagger 自动生成 HTTP 接口文档,通过 Swagger UI 界面上进行 HTTP 接口调试。如下图所示:

图片

Swagger HTTP 界面

秃头提示:对 Swagger 不太了解的胖友,可以去阅读下艿艿写的 《芋道 Spring Boot API 接口文档 Swagger 入门》 文章。

开发体验杠杠的好!但是在使用 Dubbo 构建 RPC API 时,简直想要自闭。常常面临的痛苦是:

  • 隔壁团队的老王,不肯给 Dubbo 写接口文档,只能从他的 Dubbo API 的 jar 包中寻寻觅觅想要的接口,贼不方便~

  • 自己编写的每个 Dubbo API 接口,都需要写个 Controller 或者 Test 类去调用测试,接口调试非常麻烦~

在一个逐步自闭到要爆炸的下午,艿艿做了一波 Dubbo 接口文档与接口调试的调研,想要尝试这块的痛点。结果比想象中顺利且简单,这不趁着这无聊到抠脚的周末,整理下分享给胖友。

图片

IDEA 上号

🚀 这么良心,不考虑给艿艿点个赞么?!

芳芳都说好!!!

2. Swagger Dubbo

哈哈哈~实际上,我们还是可以通过 Swagger 实现 Dubbo 的接口文档接口调试这两个功能。效果如下图:

图片

Swagger Dubbo 界面

Swagger 对 Dubbo 的支持,是通过 swagger-dubbo 项目所实现,其 Github 地址是 https://github.com/Sayi/swagger-dubbo。

图片

Swagger Dubbo 项目

2.1 小小改造

dubbo-swagger 最新版本 v2.0.1,并不支持 Dubbo 2.7.0 开始的版本,因此我们需要做一点点小小的改造。具体的改造点如下:

良心艿:怕麻烦的胖友,可以看艿艿 fork 出来的仓库 https://github.com/YunaiV/swagger-dubbo,给改的明明白白了,直接能用。

    1. 合并 PR#50 的代码,支持 Dubbo 2.7.0 开始的版本。

    1. 合并 PR#46 的代码,使 Swagger UI 界面正确展示 POJO 类型的参数。

2.2 快速入门

swagger-dubbo 项目提供了 Spring Boot + Dubbo 的示例 dubbo-provider-springboot,我们来一起看一看。

图片

dubbo-provider-springboot 示例

不过 dubbo-provider-springboot 示例暂时有一点点小“问题”,我们需要稍微修正下。

良心艿:怕麻烦的胖友,可以直接看艿艿修改后的示例地址 https://github.com/YunaiV/swagger-dubbo/blob/master/swagger-dubbo/。

2.2.1 修改依赖

示例使用 Dubbo 的版本是 2.6.0,而我们希望使用 Dubbo 的版本是 2.7.0 开始,因此需要略微修改 pom.xml 如下:

<!-- 去除 Dubbo 2.6.0 的依赖 -->
<!--  <dependency>-->
<!--   <groupId>com.alibaba</groupId>-->
<!--   <artifactId>dubbo</artifactId>-->
<!--   <version>2.6.0</version>-->
<!--   <exclusions>-->
<!--    <exclusion>-->
<!--     <groupId>org.springframework</groupId>-->
<!--     <artifactId>spring</artifactId>-->
<!--    </exclusion>-->
<!--   </exclusions>-->
<!--  </dependency>-->
<!--  <dependency>-->
<!--   <groupId>org.apache.zookeeper</groupId>-->
<!--   <artifactId>zookeeper</artifactId>-->
<!--   <version>3.5.2-alpha</version>-->
<!--  </dependency>-->
<!--  <dependency>-->
<!--      <groupId>org.apache.curator</groupId>-->
<!--      <artifactId>curator-framework</artifactId>-->
<!--      <version>4.0.1</version>-->
<!--  </dependency>-->

<!-- 引入 Dubbo 2.7.0 的依赖 -->
<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo</artifactId>
    <version>2.7.4.1</version>
</dependency>
<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-spring-boot-starter</artifactId>
    <version>2.7.4.1</version>
</dependency>
<!-- 使用 Zookeeper 作为注册中心 -->
<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-framework</artifactId>
    <version>2.13.0</version>
</dependency>
<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-recipes</artifactId>
    <version>2.13.0</version>
</dependency>
<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-client</artifactId>
    <version>4.0.1</version>
</dependency>

2.2.2 修改配置文件

修改 application.properties 配置文件,增加如下配置项:

swagger.dubbo.application.groupId=com.deepoove
swagger.dubbo.application.artifactId=dubbo-provider-springboot
swagger.dubbo.application.version=2.0.2-SNAPSHOT

通过 swagger.dubbo.application 配置项,可以知道该 Dubbo 服务的 API jar 包的 groupIdartifactIdversion 信息。

友情提示:swagger-dubbo 还提供了其它配置项,一般默认即可。感兴趣的胖友,可以看看 SwaggerDubboProperties 配置类。

2.2.3 简单测试

下面,我们来运行下 dubbo-provider-springboot 示例项目,感受下 swagger-dubbo 的具体功能。

第一步,本地运行一个 ZooKeeper 服务,作为注册中心。

第二步,执行 Application 类,将 Dubbo 服务提供者进行启动。启动成功的日志如下:

14:12:24.180 [main] INFO  o.s.b.w.e.tomcat.TomcatWebServer - Tomcat started on port(s): 8077 (http) with context path ''
14:12:24.184 [main] INFO  c.d.d.p.springboot.Application - Started Application in 3.443 seconds (JVM running for 4.109)

第三步,使用浏览器访问 http://127.0.0.1:8077/distv2/index.html 地址,进入 swagger-dubbo 提供的 Swagger UI 界面,如下图所示:

图片

Swagger Dubbo 接口文档

这里,我们已经可以看到当前 Dubbo 服务所提供的 RPC 接口文档

友情提示:访问的 Swagger UI 界面,就是我们在示例项目的 resources/static/distv2 目录下的静态资源。

第四步,我们可以任一选择一个 Dubbo API 接口,填写参数后,点击「Try it out!」按钮进行 RPC 接口调试。如下图所示:

图片

Swagger Dubbo 接口调试

通过接口调试的功能,我们可以方便的测试。

友情提示:可能有胖友会好奇,swagger-dubbo 是如何实现接口调试的功能的呢?答案可以到 DubboHttpController 类中去寻找。

简单来说,就是使用 Dubbo 提供的 Java API 获得到对应 Dubbo Consumer 对象,将 HTTP 请求参数映射成 Dubbo RPC 请求参数,最终进行调用。

3. 接入 Knife4j 作为 Swagger UI 界面

由于 dubbo-swagger 项目并未将其提供的 Swagger UI 界面封装成一个 jar 包,导致集成 dubbo-swagger 的 Dubbo 项目需要在其 resources 目录下,添加相应的 Swagger UI 的静态资源。例如说:

图片

Dubbo Swagger UI 界面的静态资源

显然,这么做是非常不优雅的,因为后续无法方便的更新 Swagger UI 的静态资源。那么,应该怎么办呢?这里艿艿先演示一种解决方案,也是目前团队所采用的,接入 Knife4j 作为 Swagger UI 界面。

秃头提示:Knife4j 是基于 Swagger 的增强解决方案,提供更强大的 Swagger 的功能,以及更易用的 Swagger UI 界面。

下面,我们继续在 dubbo-provider-springboot 示例项目上,进行改造接入。

3.1 修改依赖

修改 pom.xml 文件,引入 Knife4j Starter 依赖。具体如下:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.5</version>
</dependency>

3.2 创建 SwaggerConfiguration

创建 SwaggerConfiguration 配置类,自定义 SwaggerResourcesProvider Bean。代码如下:

@Configuration
@EnableSwagger2 // 标记项目启用 Swagger API 接口文档
public class SwaggerConfiguration {

    @Bean
    @Primary
    public SwaggerResourcesProvider newSwaggerResourcesProvider(Environment env, DocumentationCache documentationCache) {
        return new InMemorySwaggerResourcesProvider(env, documentationCache) {

            @Override
            public List<SwaggerResource> get() {
                // 1. 调用 InMemorySwaggerResourcesProvider
                List<SwaggerResource> resources = super.get();
                // 2. 添加 swagger-dubbo 的资源地址
                SwaggerResource dubboSwaggerResource = new SwaggerResource();
                dubboSwaggerResource.setName("dubbo");
                dubboSwaggerResource.setSwaggerVersion("2.0");
                dubboSwaggerResource.setUrl("/swagger-dubbo/api-docs");
                dubboSwaggerResource.setLocation("/swagger-dubbo/api-docs"); // 即将废弃,和 url 属性等价。
                resources.add(0, dubboSwaggerResource);
                return resources;
            }

        };
    }

}

艿艿先暂时不解释为什么要这么做,因为涉及到 Swagger 运行机制相关的知识,略微有点小复杂~~稍后,在「3.4 再看 SwaggerConfiguration」小节,我们在一起遨游这块知识的海洋。

图片

不想学习

3.3 简单测试

下面,我们重新运行下 dubbo-provider-springboot 示例项目,感受下 Knife4j 提供的 Swagger UI 界面。重启后,使用浏览器访问 http://127.0.0.1:8077/doc.html 地址,进行访问。如下图所示:

图片

Knife4j Swagger UI 界面

是不是相比 swagger-dubbo 提供的 Swagger UI 界面更加优秀

我们再来看看接口文档接口调试的界面,如下图所示:

接口文档 接口调试

  • 图片

  • 图片

重要提示:此时,我们可以将 resources 目录下的 Swagger UI 的静态资源删除。

艿艿这里不删除的原因,还是方便大家体验对比 = =

3.4 再看 SwaggerConfiguration

为什么我们要在 SwaggerConfiguration 配置类中,自定义一个 SwaggerResourcesProvider Bean 呢?原因是,它和 Swagger UI 界面的运行机制有关。

① Swagger UI 界面采用前后端分离的架构,通过请求 Swagger 定义的接口元数据 HTTP API,获得到每个接口的信息,展示成接口文档。

可能有点难懂,我们来看看 dubbo-swagger 项目在 dubbo-provider-springboot 示例项目中,自定义实现的接口元数据 HTTP API的返回结果,如下图所示:

图片

接口元数据 HTTP API

  • 在 paths 数组中,每一个元素对应一个接口的信息。而这些接口的信息,是通过扫描 Swagger 的注解所获取到。

课外作业:对 dubbo-swagger 项目实现的接口元数据 HTTP API,可以后续看看 SwaggerDubboController 类的代码,比较简单。

② 在理解完 Swagger 定义的接口元数据 HTTP API 之后,再来看看 Swagger 定义的资源 HTTP API。Swagger Resource 资源的作用,用于将我们使用 SpringMVC 实现的 HTTP API 进行分组。并且,每个资源对应一个接口元数据 HTTP API,用于获取该分组的接口元数据。

可能有点懵逼,我们来看看 dubbo-provider-springboot 示例项目中,资源 HTTP API的返回结果,如下图所示:

图片

资源 HTTP API

  • 蓝色部分】Swagger 默认实现了一套 Swagger 资源的逻辑,通过 InMemorySwaggerResourcesProvider 的 #get() 方法,进行获取。我们在使用 SpringMVC 实现的 HTTP API 接口,就属于该 Swagger 资源。

  • 红色部分swagger-dubbo 自定义了一套 Swagger 资源的逻辑,所以我们需要手动添加一个名字为 dubbo 的 Swagger Resource 分组,集成到 Swagger 体系中。

现在,胖友是不是能够理解 SwaggerConfiguration 配置类的作用了。

③ 我们再使用浏览器访问 http://127.0.0.1:8077/doc.html 地址,进一步感受与理解。如下图所示:

图片

重看 Knife4j Swagger UI 界面

可能胖友会有一个疑惑,为什么我们在使用 swagger-dubbo 提供的 Swagger UI 界面时,不用创建 SwaggerConfiguration 配置类呢?因为它不考虑存在多 Swagger Resource 资源的情况,直接请求 swagger-dubbo 提供的接口元数据 HTTP API。如下图所示:

图片

重看 swagger-dubbo Swagger UI 界面 Swagger UI 界面

3.5 其它解决方案

除了接入 Knife4j 作为 Swagger UI 界面的方案外,还有两种方案:

① 方案一,将 swagger-dubbo 提供的 Swagger UI 的静态资源,部署到 Nginx 下。这样,我们就可以访问 Nginx 下的 Swagger UI 界面,填写需要查看 Dubbo 服务的接口元数据 HTTP API 即可。如下图所示:

图片

swagger-dubbo` Swagger UI 界面 Swagger UI 界面

② 方案二,将 swagger-dubbo 提供的 Swagger UI 的静态资源,打包成名字为 swagger-dubbo-ui 的 jar 包。这样,每个 Dubbo 服务提供者的项目,引入该 jar 包即可。具体可参考 Knife4j 的 knife4j-spring-ui 的做法,如下图所示:

图片

knife4j-spring-ui

4. 接入 YApi 统一管理

随着 Dubbo 服务越来越多,我们需要一个 API 平台能够查看到所有的 Dubbo 服务的 RPC API 接口信息。目前,艿艿比较推荐和使用的 YApi 平台,主要原因是 YApi 可以采集 Swagger 提供的接口元数据 HTTP API,自动进行同步接口信息的同步。

秃头提示:对 YApi 不太了解的胖友,可以去阅读下艿艿写的 《芋道 Spring Boot API 接口文档 Swagger 入门》 的「4. 更强大的 YApi」小节。

具体的效果,胖友可以看看如下图:

项目列表 项目详情

  • 图片

  • 图片

dubbo-swagger 提供的接口元数据 HTTP API,路径是 /swagger-dubbo/api-docs。至于如何配置定时采集,可参考如下图:

图片

定时采集

666. 彩蛋

至此,我们通过多个开源项目的组合,实现 Dubbo 的接口文档接口调试的功能。简单来总结下:

  • 基于 Swagger Dubbo 项目,实现 Dubbo RPC API 的接口文档接口调试的功能。

  • 基于 Knife4j 项目,提供更强大的 Dubbo Swagger UI 界面。

  • 基于 YApi 项目,作为统一的 API 管理平台,可以查看所有 Dubbo 项目的 API 接口文档、进行接口调试

当然,如果我们要将该方案落地到公司的 Dubbo 项目中,还有一些事情需要去做:

  • 1、将修改后的 dubbo-swagger 项目,重新编译打包,推送到公司的 Nexus 私服。毕竟,咱也不知道 dubbo-swagger 项目啥时候会支持 Dubbo 2.7.0 开始的版本。

  • 2、编写公司的 Swagger Dubbo Starter,将对 Knife4j 的整合进行自动配置。

  • 3、尝试基于 YApi 提供的 mock 功能,实现 Dubbo 服务的 mock 能力,以便更好的并行开发。

  •   这是我整理的《2024最新Python自动化测试全套教程》,以及配套的接口文档/项目实战【网盘资源】,需要的朋友可以下方视频的置顶评论获取。肯定会给你带来帮助和方向。

    【已更新】B站讲的最详细的Python接口自动化测试实战教程全集(实战最新版)

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.coloradmin.cn/o/1995188.html

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈,一经查实,立即删除!

相关文章

论文阅读笔记:Semi-Supervised Semantic Segmentation Using Unreliable Pseudo-Labels

论文阅读笔记&#xff1a;Semi-Supervised Semantic Segmentation Using Unreliable Pseudo-Labels 1 背景2 创新点3 方法4 模块4.1 伪标签4.2 使用不可靠的伪标签 5 效果5.1 与SOTA方法对比5.2 消融实验5.3 定性结果 6 结论 论文&#xff1a;https://arxiv.org/pdf/2203.03884…

北京崇文门中医院贾英才主任:战胜头晕,重获“清醒人生”

头晕&#xff0c;这个看似常见却又恼人的症状&#xff0c;常常让患者的生活陷入困境。在北京崇文门中医院&#xff0c;有个叫贾英才的医生&#xff0c;他凭借医术&#xff0c;给不少头晕患者带去了希望。 北京崇文门中医院贾英才主任在医学领域辛勤耕耘多年&#xff0c;对于头晕…

ubuntu20从docker安装到制作自己的镜像使用记录

ubuntu20从docker安装到制作自己的镜像使用记录 第一章&#xff1a;配置环境 1.ubuntu20 2.docker镜像18.04 3.参考&#xff1a;https://www.runoob.com/docker/docker-tutorial.html 第二章&#xff1a;安装docker 一、安装docker 参考1&#xff1a;Ubuntu安装docker并运…

Spring Cloud微服务项目文件上传/下载

在现代的微服务架构中&#xff0c;文件上传与下载是常见的需求&#xff0c;尤其是在需要处理大量文件数据的系统中。Spring Cloud 提供了灵活的工具和组件&#xff0c;使得在微服务中实现文件上传和下载变得高效而简便。 本文博主将详细介绍如何在 Spring Cloud 微服务项目中实…

【Kubernetes】k8s集群之Pod容器资源限制和三种探针

目录 一、Pod容器的资源限制 1.资源限制 2.Pod 和容器的资源请求与限制 3.CPU 资源单位 4.内存资源单位 二、Pod容器的三种探针 1.探针的三种规则 2.Probe支持三种检查方法&#xff1a; 一、Pod容器的资源限制 1.资源限制 当定义 Pod 时可以选择性地为每个容器设定所…

成都数字产业中心崛起,树莓集团如何加速国际数字影像产业园的全球步伐?

在数字化浪潮的推动下&#xff0c;成都数字产业中心近年来强势崛起&#xff0c;展现出令人瞩目的发展态势。据统计&#xff0c;过去五年间&#xff0c;成都数字产业的年均增长率超过了 20%&#xff0c;这一数据充分证明了其强大的发展动力。而在这片充满活力与创新的土地上&…

数据结构 JAVADS ——部分栈题目分享 (持续更新版)

前言 大概十天前,笔者更新了如何手搓一个简易的栈 入门数据结构JAVA DS ——手搓 栈-CSDN博客 在本篇博客中,笔者就分享几个题目,这同样是一个持续 更新的博客,但是我不保证更新频率就是了 哈哈! 那么我们就来看题目吧 第一题 1.小蓝的括号串1 - 蓝桥云课 (lanqiao.cn) …

如何在 Windows 上设置 MacOS 云主机

在Windows上设置MacOS云主机实际上涉及在Windows环境中模拟或远程管理MacOS系统&#xff0c;因为直接在Windows上运行MacOS作为云主机的主操作系统是不可能的&#xff0c;因为MacOS是为苹果硬件设计的。不过&#xff0c;有几种方法可以实现类似的功能&#xff1a; 1. 使用虚拟机…

Haskell HTTP请求:如何解读响应状态

在互联网技术领域&#xff0c;HTTP请求是客户端与服务器之间通信的基础。无论是网页浏览、API调用还是网络服务的交互&#xff0c;HTTP协议都扮演着核心角色。在本文中&#xff0c;我们将探讨如何在Haskell编程语言中发起HTTP请求&#xff0c;并重点介绍如何解读HTTP响应状态。…

学懂C++ (二十一):高级教程——深入C++多线程开发详解

C多线程开发详解 多线程编程是现代应用程序开发中不可或缺的一部分。C11引入了对多线程的支持&#xff0c;使得程序员能够更方便地利用多核处理器&#xff0c;提高程序的性能和响应能力。本文将全面而深入地探讨C的多线程相关概念&#xff0c;包括线程的创建与管理、互斥量…

PDF怎么在线转Word?介绍四种转换方案

PDF怎么在线转Word&#xff1f;在数字化办公时代&#xff0c;文档的互换性变得尤为重要。PDF格式因其跨平台兼容性和版面固定性而广受欢迎&#xff0c;但有时我们可能需要将PDF文件转换为Word文档&#xff0c;以便进行编辑或进一步处理。以下是四种常见的在线PDF转Word的方法&a…

大数据湖体系规划与建设方案(51页PPT)

方案介绍&#xff1a; 大数据湖通过集中存储各种类型的数据&#xff08;包括结构化、半结构化和非结构化数据&#xff09;&#xff0c;提供了更加灵活、可扩展的数据处理和分析能力。其核心理念是“存储一切&#xff0c;分析一切&#xff0c;创建所需”&#xff0c;即将所有数…

【论文复现】Transformer

Transformer 前言网络架构数据处理词嵌入向量位置编码 模型定义多头注意力机制编码器Encoder解码器Decoder 前言 Transformer应用范围非常广泛&#xff0c;涵盖了自然语言处理、时间序列数据预测、图像处理等领域。由于笔者之前都是应用&#xff0c;但是对于原理并没有深刻理解…

树莓派Pico 2,RP2350 现已发售!

https://www.bilibili.com/video/BV1n5YeeMETu/?vd_sourcea637ced2b66f15709d16fcbaceeb47a9 我们很高兴地宣布推出Raspberry Pi Pico 2&#xff0c;我们的第二代微控制器板&#xff1a;采用了由我们自主设计的新款高性能安全型微控制器 RP2350。 Raspberry Pi Pico 2&#…

5 种经过验证的查询翻译技术可提高您的 RAG 性能

如何在用户输入模糊的情况下获得近乎完美的 LLM 性能 欢迎来到雲闪世界。你认为用户会向 LLM 提出完美的问题&#xff0c;这是大错特错。如果我们不直接执行&#xff0c;而是细化用户的问题&#xff0c;结果会怎样&#xff1f;这就是查询转换。 我们开发了一款应用程序&#x…

查看DrawCall流程 Unity工具 Frame Debug

切换帧率 基础面板 可以看到 我们可以通过切换面板 看DrwaCall产生 MainTex 就是材质了 如何优化&#xff1f; 合批 就会一次性直接渲染

双端队列Deque

Deque&#xff08;双端队列&#xff09;是一种允许在两端都进行插入和删除操作的线性数据结构。它在 Java Collections Framework 中作为一个重要的接口&#xff0c;具有以下结构特点&#xff1a; 1. 双端操作 两端插入和删除&#xff1a;与传统队列&#xff08;只能在一端入…

迭代次数顺序的双重性

(A,B)---6*30*2---(0,1)(1,0) 收敛误差为7e-4&#xff0c;收敛199次取迭代次数平均值&#xff0c; 让A是4a1&#xff0c;4a2&#xff0c;…&#xff0c;4a16&#xff0c;B全是0得到迭代次数的顺序就是1&#xff0c;2&#xff0c;…&#xff0c;16. 但是如果让训练集A-B矩阵的高…

kafka-go使用:以及kafka一些基本概念说明

关于kafka 作为开发人员kafka中最常关注的几个概念&#xff0c;是topic,partition和group这几个概念。topic是主题的意思&#xff0c;简单的说topic是数据主题&#xff0c;这样解释好像显得很苍白&#xff0c;只是做了个翻译。一图胜前言&#xff0c;我们还是通过图解来说明。…

PDF密码移除技巧: 五大 PDF 密码移除器

如果您想解密或删除 PDF 密码&#xff0c;该怎么办&#xff1f;PDF 是一种经常用于商业的格式&#xff0c;您可以在培训、教育和商业场合使用它。添加这些 PDF 文件的密码可以保护您的安全和隐私。因此&#xff0c;有很多 PDF 都用密码加密&#xff0c;当您想要查看这些 PDF 时…