前言
在开发前端应用程序时，API 是必不可少的一种复杂数据交互方式。通常使用的构建 API 的方式为设计和文档化 OpenAPI 规范。而 OpenAPI 规范 中定义了 API 的结构、请求参数、响应内容等信息，几乎覆盖了 API 开发和文档化中的所有方面。
本文将介绍如何使用 npm 包 @readme/oas-tooling 来处理 OpenAPI 规范，以帮助我们更好地开发和文档化 API。
概述
@readme/oas-tooling 是一个帮助我们生成、处理 OpenAPI 规范的 npm 包。借助该包，我们可以完成以下任务：
- 从 OpenAPI 规范生成 API 文档
- 从 GitHub 或 GitLab 生成 API Mock 数据并支持其动态更新
- 生成 API 请求代码和文档
接下来将详细解释如何使用该 npm 包。
安装
使用 npm 安装 oas-tooling：
npm install --save-dev @readme/oas-tooling
从 OpenAPI 规范生成 API 文档
以下是从 OpenAPI 规范生成文档的指南：
- 使用 Swagger UI、ReDoc 或 Slate 等提供的文档化工具之一，将 OpenAPI 规范渲染为网页文档
- 从
dist目录下的标志中托管网页文本
-- -------------------- ---- -------
----- - ------- ------- - - -------------------------------
-- ------
--------
------ --------------------- -- ------- -------
------- ---------- -- ----------
-------- -
-- ------
-
------- --------------- -- --- --- -----------------
------- ------------------------
--
-
------- --------------- -- --- ---------- -----------------
-------- -----------------------
--
--
---
-- ------------
---------
------ ----------
--------- --------------------------
------ -----------
---从 GitHub 或 GitLab 生成 API Mock 数据并支持其动态更新
以下是从 GitHub 或 GitLab 生成 Mock 数据的指南：
- 在 GitHub 或 GitLab 上创建新存储库，并在存储库的根目录下创建 OpenAPI 文件
- 在 GitHub 或 GitLab 上创建 Actions Pipeline 或 GitLab CI。
- 运行 @readme/oas-mock-server，将 API 定义实例化为可运行的 Mock API 服务
-- -------------------- ---- -------
----- - ------------ - - -----------------------------------
--------------
---- --------------------- -- ------- -------
------- -
----- ----- -- -- ----
----- ----- -- -----
--
------- -
---- -------
--------- ------------------------------- -- ------ ------ -----
------ -----------
--
------- -
---- ---------
----------- ----- -- -------- -- - ------ -- -- -- ----
------ -----------
---- ---------------------
--
---------------- -- -
----------------- ------ ------- -- ---- -----------------
---生成 API 请求代码和文档
以下是生成 API 请求代码和文档的指南：
- 文档化你的 API
- 生成 API 的代码样板
-- -------------------- ---- ------- ----- - ---------- ---------------- -------------- - - ------------------------------- ----- -------- - --------------------- -- ------ ----------- ------ - ----------- - ---- -------------------- ------ - -------- - ---- ---------------- --- -- ----- ------- ------------- -- ----- ------- - ------- ------- ------ -------- ---------- --- ------ ------ -- -------- - ----- - ----- ------- - - ------------------------- ----- ------- -------- ----------------------------- --------- -- -------- -
- 自定义你的 API 请求代码
以上脚本将根据规范生成请求代码，这些请求可以进入任何 JavaScript web 应用程序。我们可以定制从规范生成的代码以满足特定的需求。如果我们将代码样板中的请求发现开发环境中发生错误，则可以自定义错误处理程序。
结论
@readme/oas-tooling 是一个非常有用的工具，尤其是在需要文档化和消费 API 时。正如我们在本文中所看到的，我们可以使用 oas-tooling 来生成文档、Mock API 和生成 API 请求类型的代码。
我们鼓励您在编写自己的应用程序时使用该包，并从中获得技能和见解。如有问题，请参阅该 npm 包的官方文档。
示例代码
完整的示例代码可以在以下存储库中找到：https://github.com/username/repo。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedb0c6b5cbfe1ea06110e9