介绍
OpenAPI 规范是当前非常流行的 RESTful API 的规范,大多数公司的 Web API 文档都是使用 OpenAPI 规范来定义的。在这个规范中,有两个版本:OpenAPI 2.0 和 OpenAPI 3.0。OpenAPI 3.0 又比 OpenAPI 2.0 更加严格、更加标准化,而且对于 JSON Schema 的支持也得到了很大的改进。
然而,由于历史原因,很多公司的 Web API 已经使用了 OpenAPI 2.0 规范来定义,并且已经发布了相应的文档。因此,当我们需要将这些 Web API 升级到 OpenAPI 3.0 规范时,需要手动地将 OpenAPI 2.0 规范转换成 OpenAPI 3.0 规范。手动转换会非常繁琐和费时,因此我们可以使用 npm 包 @microsoft.azure/oai2-to-oai3 来进行转换。
安装
通过 npm 安装
npm i -g @microsoft.azure/oai2-to-oai3
通过源码安装
git clone https://github.com/microsoft/oai-ts-to-oai.git cd oai-ts-to-oai npm install npm run build
使用
命令行
我们可以使用以下命令行将 OpenAPI 2.0 规范转换成 OpenAPI 3.0 规范:
oai2-to-oai3 -f openapi2-file.yaml -o openapi3-file.yaml
JavaScript
我们也可以在 JavaScript 代码中使用 @microsoft.azure/oai2-to-oai3 包:
-- -------------------- ---- ------- ----- ------------------ - ---------------------------------------- ----- -------- - - -------- ------ ----- ------ ------ ------ --- - ----- -------- - ----------------------------
示例
OpenAPI 2.0 规范文件
-- -------------------- ---- ------- -------- ----- ----- ------ ------ --- ------------ ---- -- - ------ --- ---------- --- ------- ---- -------- ----- --------- ---- -------- - ----- ------ ------ ---- ----- - ---- -------- -------- - ---- -- ------ ------------ ---- -------- --------- - ---- -- ------ --------- - ---------------- ---------- ------ ------------ - ---- -- ------ ------- ----- ----- ------ ----- -------------------- --------- - ------- -- ----- ----- - ---- -------- ------ - --- ----- ------------ ---- -------- ------- - --- ----- --------- - ---------------- ----------- - ----- ---- --- ---- --------- ---- ------- ----- -------------------- ---------- ------ ------------ --- ----- ------- ----- ------- ----- -------------------- --------- - ------- -- ------------ ----- ----- ------ ----------- --------- ----- ------ --------- ----- ------ ------ ----- ------
OpenAPI 3.0 规范文件
-- -------------------- ---- ------- -------- ----- ----- ------ ------ --- ------------ ---- -- - ------ --- ---------- --- ------- ---- -------- ----- -------- - ---- -------------------------- --------- ---- -------- - ----- ------ ------ ---- ----- - ---- -------- -------- - ---- -- ------ ------------ ---- -------- --------- - ---- -- ------ ---------- ------ ------------ - ---- -- ------ -------- ----------------- ------- ----- ----- ------ ----- --------------------------- --------- - ------- -- ----- ----- - ---- -------- ------ - --- ----- ------------ ---- -------- ------- - --- ----- ------------ --------- ---- -------- ----------------- ------- ----- --------------------------- ---------- ------ ------------ --- ----- ------- ----- -------- ----------------- ------- ----- --------------------------- --------- - ------- -- ----------- -------- ----- ----- ------ ----------- --------- ----- ------ --------- ----- ------ ------ ----- ------
总结
@microsoft.azure/oai2-to-oai3 包可以帮助我们快速将 OpenAPI 2.0 规范转换成 OpenAPI 3.0 规范。我们可以通过命令行或者 JavaScript 代码来使用它。本文介绍了如何安装和使用 @microsoft.azure/oai2-to-oai3 包,并提供了相应的示例代码。希望这篇文章能够帮助您更好地了解 OpenAPI 规范的转换和使用。
来源:JavaScript中文网 ,转载请注明来源 https://www.javascriptcn.com/post/600673e0fb81d47349e53cd8