npm 包 @readme/oas-tooling 使用教程

阅读时长 7 分钟读完

前言

在开发前端应用程序时,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

从 OpenAPI 规范生成 API 文档

以下是从 OpenAPI 规范生成文档的指南:

  1. 使用 Swagger UIReDocSlate 等提供的文档化工具之一,将 OpenAPI 规范渲染为网页文档
  2. dist 目录下的标志中托管网页文本
-- -------------------- ---- -------
----- - ------- ------- - - -------------------------------

-- ------
--------
  ------ --------------------- -- ------- -------
  ------- ---------- -- ----------
  -------- -
    -- ------
    -
      ------- --------------- -- --- --- -----------------
      ------- ------------------------
    --
    -
      ------- --------------- -- --- ---------- -----------------
      -------- -----------------------
    --
  --
---

-- ------------
---------
  ------ ----------
  --------- --------------------------
  ------ -----------
---

从 GitHub 或 GitLab 生成 API Mock 数据并支持其动态更新

以下是从 GitHub 或 GitLab 生成 Mock 数据的指南:

  1. 在 GitHub 或 GitLab 上创建新存储库,并在存储库的根目录下创建 OpenAPI 文件
  2. 在 GitHub 或 GitLab 上创建 Actions PipelineGitLab CI
  3. 运行 @readme/oas-mock-server,将 API 定义实例化为可运行的 Mock API 服务
-- -------------------- ---- -------
----- - ------------ - - -----------------------------------

--------------
  ---- --------------------- -- ------- -------
  ------- -
    ----- ----- -- -- ----
    ----- ----- -- -----
  --
  ------- -
    ---- -------
    --------- ------------------------------- -- ------ ------ -----
    ------ -----------
  --
  ------- -
    ---- ---------
    ----------- ----- -- -------- -- - ------ -- -- -- ----
    ------ -----------
    ---- --------------------- 
  --
---------------- -- -
  ----------------- ------ ------- -- ---- -----------------
---

生成 API 请求代码和文档

以下是生成 API 请求代码和文档的指南:

  1. 文档化你的 API
  2. 生成 API 的代码样板
-- -------------------- ---- -------
----- -
  ----------
  ----------------
  --------------
- - -------------------------------

----- -------- - ---------------------

-- ------
-----------
------ - ----------- - ---- --------------------
------ - -------- - ---- ----------------
---

-- ----- ------- ------------- --

----- ------- - ------- ------- ------ -------- ----------

--- ------ ------ -- -------- -
  ----- - ----- ------- - - ------------------------- ----- ------- --------

  ----------------------------- --------- -- --------
-
  1. 自定义你的 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

纠错
反馈