swagger2升级至openapi3的利器--swagger2openapi

IT布道2025-04-30 18:08

背景：

因为项目需要升级JDK，涉及到swagger2升级至openapi3的情况。由于swagger 2和openapi 3的语法差距太大，需要对yaml进行升级。无奈单个yaml文件的内容太大，高至4万多行，手动进行语法的转换肯定是不可能了，swagger 3提供的在线编辑器当遇到文件过大时，页面也会宕机。所以，我们需要借助工具来实现语法间的转换，于是，我找到了swagger2openapi这个工具。

什么是 swagger2openapi？

官网对其介绍很简单，一句话概括了：Convert Swagger 2.0 definitions into OpenApi 3.0.x。swagger2openapi 是一个开源工具，用javascript写的，托管在GitHub 上，并通过 npm 发布。

安装 swagger2openapi：

因为swagger2openapi 是一个 Node.js 工具，所以需要 Node.js 环境，如果没有Node.js，则需要先安装Node.js，这里就不介绍Node.js的安装方式了，需要的自行百度。需要注意的是Node.js的版本问题，比如，我使用的swagger2openapi的版本是7.0.8，他需要Node 12的版本。接下来回到swagger2openapi的安装部分：

命令行输入以下命令，全局安装的模式：

复制代码

npm install -g swagger2openapi

验证安装是否成功：

复制代码

swagger2openapi --version

如果输出了版本信息，说明安装成功了。

使用方法：

swagger2openapi 提供了多种使用方式，包括命令行、Node.js 模块、Docker 和 VS Code 扩展。下面就介绍命令行的使用吧，其他的请参考官网。

命令行使用，基本语法：

复制代码

swagger2openapi [options] <input-file> [--outfile <output-file>]

举个例子：

bash 复制代码

swagger2openapi swagger.yaml -o openapi.yaml ---patch

强烈建议加上--patch参数，它可以修复一些小的问题，比如，openapi要求某些参数必须有description，加上--patch参数，就可以在转换的同时，自动帮你加上。

转换完成之后就是验证工作了，它转换出来的可能并不是完美的，所以，需要根据编译的结果进行修复。但是可以解决大部分的问题，已经提高了不少效率了。

另外，这个工具转换速度很快，相当推荐！