Swagger 是一个用于设计、构建和文档化 RESTful Web 服务的工具集，该工具集包含了一系列的规范和工具，可以使得构建 Web 服务更加简单和快捷。其中，Swagger Codegen 是一个可以根据 Swagger 规范自动生成 API 代码的工具，它支持多种语言和框架，包括 JavaScript 和 Node.js。在本文中，我们将介绍一款名为 @slightlytyler/swagger-js-codegen 的 npm 包，它是 Swagger Codegen 的 JavaScript 实现。
安装
使用 npm 安装 @slightlytyler/swagger-js-codegen：
npm install -g @slightlytyler/swagger-js-codegen
使用全局安装可以在命令行中直接使用 swagger-js-codegen 命令，而不需要每次使用都输入完整的路径。如果不想使用全局安装，可以在项目中添加对该包的依赖，然后在命令行中使用 npx swagger-js-codegen 命令。
使用
生成代码
使用 @slightlytyler/swagger-js-codegen 生成代码的命令为 swagger-js-codegen generate，下面是该命令的详细参数：
swagger-js-codegen generate -i [Swagger 规范文件路径] -l [目标语言（默认为 javascript）] -o [输出目录] [其他选项]
其中，最重要的参数是 -i，该参数指定 Swagger 规范文件的路径。在使用该命令之前，我们需要先获得一个 Swagger 规范文件，该文件定义了 Web 服务的 API 结构和请求/响应参数，文件格式通常为 YAML 或 JSON。Swagger 规范文件的编写和使用可以参考 Swagger 官方文档和其他相关教程，这里不再赘述。下面是一个简单的 Swagger 规范文件的示例：
-- -------------------- ---- -------
-------- -----
-----
------ -- ---
-------- -----
------
-------
----
-------- -----
-----------
- ----- ----
--- -----
------------ ------
--------- -----
----- ------
----------
------
------------ --
-------
----- ------使用以下命令生成 JavaScript 代码：
swagger-js-codegen generate -i swagger.yaml -o code -l javascript
该命令将生成一些 JavaScript 代码到 code 目录中，包括一个包含 API 方法的模块文件和一个用于生成模块的测试文件。生成的模块使用了 axios 这个流行的 HTTP 客户端库，可以在 Node.js 或浏览器环境中使用。
使用 API
生成的代码包含了一个简单的 API 方法 getHello，该方法用于获取问候语。我们可以在一个 Node.js 模块中使用该方法，示例如下：
-- -------------------- ---- -------
----- --- - ------------------------
-------------------
-------------- -- -
--------------------------
--
------------ -- -
--------------------
--该代码将发送一个 GET 请求到 /hello 接口，并在控制台输出响应数据。注意，该方法的参数不需要包含请求地址和查询参数，因为这些信息已经在 Swagger 规范文件中定义好了。我们只需要提供规范文件中定义的参数即可。若 Swagger 规范文件中有多个参数，则可以将它们作为一个对象传递给方法。例如：
api.getHello({ name: 'Tom', lang: 'en' })高级用法
在生成 Swagger 代码之后，我们可以选择对它进行更多的定制和扩展。下面是一些示例：
更改默认配置
可以在生成代码之前修改一些默认配置，例如 API 中使用的 HTTP 客户端库、生成代码的输出格式等等。这可以通过在规范文件的 Swagger 根对象中添加 x-codegen-options 子对象来实现。下面是一个示例：
-- -------------------- ---- -------
-------- -----
-----
------ -- ---
-------- -----
------------------
--------- -----
------- -----
------
-------
----
---该配置将指定使用 xhr 这个 HTTP 客户端库，并将生成的代码格式设置为 ES6 模块格式。
自定义 API 方法
可以在生成代码之后对 API 方法进行修改和扩展。例如，我们可以添加一些验证逻辑、记录请求/响应日志等等。下面是一个示例：
-- -------------------- ---- -------
----- --- - ------------------------
----- ---------------- - ----- ------ ------ -- -
-- -------- -
----- --- ------------- ------- - --------
-
--- -
----- -------- - ----- ------------------ - -------- - -------------- ------- --------- - --
-- ----
--------------------- --- ----------------------
- ---------- ------------------ -------------------------
- -------------------
------ --------
- ----- ------- -
---------------------- ------- --- ---------------------- - --------------
----- -----
-
-
----------------------- --------该方法使用了 api.getHello，并添加了一个额外的参数 token 用于验证。在发送请求之前，它会检查 token 是否存在，如果不存在则抛出一个错误；在接收到响应之后，它会记录请求和响应日志。
生成 TypeScript 代码
可以使用 typescript-fetch 语言设置生成 TypeScript 代码。以类似 swagger.yaml 文件为例，下面是生成代码并使用:
swagger-js-codegen generate -i swagger.yaml -o code -l typescript-fetch cd code npm i @types/node npx tsc -p . node index.js
生成出的代码包含了对 axios 的依赖，包装了运行于 node 环境。之后效果与使用 JavaScript 相同。 生成文件还包含了在 node 环境中没有定义的一些类型。 使用 npx tsc -p . 将之编译成 JS 代码之后就能运行了。
总结
@slightlytyler/swagger-js-codegen 是一个非常方便的工具，它可以快速地生成具有良好结构和清晰接口的 API 代码。在使用 swagger-js-codegen 生成代码之前，我们需要仔细编写 Swagger 规范文件来正确描述 Web 服务的 API 结构和参数。生成的代码可以轻松地与多种 Web 开发框架集成，可以方便地用于 Web 应用程序和其他项目中。除了以上提到的功能之外，Swagger 还提供了丰富的功能和扩展性，如数据模型定义、API 文档自动生成等，欢迎大家深入了解。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60057cb781e8991b448ebffd