在前端开发中，通过 RESTful API 与后端交互是一项基本任务，而 OpenAPI 规范（Swagger）是其中最受欢迎和可靠的方法之一。因此，许多开发者都选择使用 OpenAPI 定义和文档化他们的 API。
然而，手写 OpenAPI 文档往往是一项繁琐的任务，且易制造错误。在本文中，我们将介绍如何使用 npm 包 fluent-openapi 来生成符合 OpenAPI 规范的文档，以及在此基础上做更多扩展来提高开发效率。
安装
首先，我们需要使用 npm 安装 fluent-openapi。在命令行中输入以下命令：
npm install fluent-openapi --save-dev
注意，我们将它加入到开发依赖中，因为它只用于生成 OpenAPI 文档。
使用方法
接下来，我们将了解如何使用 fluent-openapi 生成 OpenAPI 文档。
基础使用
下面是一个示例代码，它使用 fluent-openapi 来创建一个对 /users 路由的 GET 请求的 OpenAPI 文档：
-- -------------------- ---- -------
----- -------------- - --------------------------
----- -------------- - -----------------------
-------- --------
----- ------- --- ----- -------- ---------
-------- ------ --------------------------
---
----- -------------- - --------------
---------------
------- ------
----- ---------
------------ -------- - ---- -- --------
--
------------------ --------- ------- - ---- -- --- --------
-------------- --- ----- -- --------
-------------- --- ----- ---- ---------
----- ---------- - -------------------------
------------------------如上所示，我们首先导入 fluent-openapi，并使用 OpenApiBuilder.create() 创建一个新的 OpenAPI 构建器。我们可以在构造函数中传递一些元数据，如 API 的基本信息和服务器地址。在当前示例代码中，我们指定了 API 的名称和版本和本地服务器地址。
接下来，我们可以使用 addOperation() 方法来添加一个新的操作。在当前示例代码中，我们定义了一个 GET /users 路由，以及一些额外的描述信息。我们还使用 description() 方法来添加操作的详细说明。最后，我们使用 response() 方法来定义实际响应，以及 HTTP 状态代码和响应的类型。
最后，我们使用 getSpec() 方法来获取最终文档对象，并将其打印到控制台。
更多功能
上述示例只是最基本的 fluent-openapi 用法示例。fluent-openapi 还支持许多其他功能，让我们在这里介绍一些。
定义请求体和响应体
如果您需要定义 API 请求和响应的详细内容，则可以使用 requestBody() 和 responseBody() 方法。
在下面的示例代码中，我们为 /users/{userId} 路径下的 PUT 请求添加了请求体，以及为响应添加了一个特定的响应体：
-- -------------------- ---- -------
----- -------------- - --------------
---------------
------- ------
----- ------------------
------------ -------- - -------
--
------------------------ ---- ---- -----
------------------ --------- ------- - -------- -------
-------------
-------------
---- ---- ---- -- ---------
------------------------------------------------
-
----------
----
---- ------- ---- --------
------------------------------------------------
-
-------------- ---- ------- --- ----------
-------------- --- ---- --- ----- ---- --- ----- ------在上面的代码中，我们使用 requestBody() 方法来定义请求体，它接受三个参数：
- 请求体的名称；
- 请求体的描述；
- 第三个参数是一个 JSON 对象，可以是原始数据类型或对应于其他文档部分的 $ref 属性。在上面的代码示例中，我们使用 $ref 属性链接到用户对象的定义。
在接下来的 response() 方法中，我们使用类似的方式来定义特定的响应体。其中，OpenApiBuilder.$ref() 函数用于引用其他部分的 $ref 属性。
定义请求参数和响应头
与请求体类似，参数和响应头也可以有自己的描述信息。因此，fluent-openapi 还提供了 requestParameter() 和 header() 方法。
在下面的示例代码中，我们为 /users/{userId} 路径下的 GET 请求添加了一个请求参数和一个自定义响应头：
-- -------------------- ---- -------
----- -------------- - --------------
---------------
------- ------
----- ------------------
------------ -------- - -------- -------
--
------------------------ ---- ---- -----
------------------ --------- --------- - -------- -------
------------------
---------
---- ------ -- ------- -- --- -----------
-----
-----------------------
------------------------------------- -------- ---------
-
-
-------------- ---- --------- ------- -------------------------------------------------
-------------------------- -- ------ ---------
-------------- ---- ------- --- ----------
-------------- --- ---- --- ----- ---- --- ----- ------在上面的代码中，我们使用 requestParameter() 方法定义了一个查询参数 fields，并使用 enum() 方法定义了字段的有效值。相应地，我们使用 header() 方法在响应中定义了一个自定义响应头。
引用外部文档
最后，如果我们需要引用外部文档，则可以使用 $ref 属性。这允许我们重用先前定义的组件，以避免重复代码。
在下面的示例代码中，我们引用了一个简单的用户对象，在 /components/schemas 中定义。注意，我们在前面的示例代码中已经引用了该对象。
-- -------------------- ---- -------
----- ----------- - -
----- -
----- ---------
----------- -
----- ------ --------- ------------ ---- ---- --------
------ ------ --------- ------------ ---- ---- ---------
------ ------ --------- ------------ ---- ---- ----- ----------
--
--------- -------- ---------
--
--
----- -------------- - -----------------------
---
----------- --------- -------------
---在上面的代码中，我们创建了一个名为 userSchemas 的对象，其中包含所有用户对象定义。然后，我们将其传递给 OpenApiBuilder.create() 的 components 选项。在 addOperation() 方法中，我们使用 OpenApiBuilder.$ref() 函数来引用它。
总结
在本文中，我们介绍了 npm 包 fluent-openapi 的基础知识和使用方法。我们看到了如何使用 fluent-openapi 创建并定义操作、请求和响应属性、请求体和响应体、参数和响应头，以及如何引用外部文档。这些功能让我们更轻松和快速地创建符合 OpenAPI 规范的文档，提高开发效率。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60066bce967216659e244c7d