前言
在现代化的 Web 应用程序中，越来越多的人选择使用 Swagger 开发 RESTful API。Swagger 是一个规范和完整的框架，用于生成、描述、消费 RESTful 风格的 Web 服务。 它包括各种工具，可以自动生成文档和客户端 SDK。 这就是 Foxify Swagger Generator 要做的事情。
Foxify Swagger Generator 是一个强大的自动生成 Swagger 文档的工具，可以自动生成 API 文档和客户端 SDK。这个工具是基于 Foxify 框架构建的，并使用 Node.js 编写。通过本文的教程，您将了解到如何安装和使用该工具。
安装
要使用 Foxify Swagger Generator，需要先安装 Node.js 和 npm 包管理器。完成这些步骤后，使用以下命令安装 Foxify Swagger Generator:
npm install foxify-swagger-generator
一个常见的方式是在你的项目根目录下安装它，这样你可以使用内置的 Foxify 来自动化为你的 API 生成 Swagger.json 文档。
配置
接下来，使用以下代码配置 Foxify Swagger Generator:
-- -------------------- ---- -------
--- ------ - ------------------
--- ---------------------- - ------------------------------------
--- --- - ---------
--- ------- - -
------------------ -
----- -
------ --- -----
-------- --------
------------ --------------
--
--------- ----
--------- -------------------- -------------------
-------- -------- ---------
-------------------- -
---- -
------------ ---
----- ---------
----- ----------------
--- ---------
--
--
--
-------- ---------- ----- -------- ----
------ --------------------- ------ -- --- --- ------ ------
--
-------------------------------------
---------------- -------- -- -
---------------- ------- -- ---- -------
--以上代码：
- 创建一个名为
app的 Foxify 应用程序实例。 - 使用包含 API 信息的对象设置
swaggerDefinition。 - 指定
options对象的值来告诉 Foxify Swagger Generator 相关的 API 源码路径以及一些其他配置。 - 使用
foxifySwaggerGenerator导出函数，传入app和options作为参数，并调用它以在 Foxify 应用程序中启用 Swagger。
生成 Swagger 文档
完成了必要的配置后，执行以下命令, Foxify Swagger Generator 将自动生成 Swagger.json 文件。
curl http://localhost:3000/swagger.json > swagger.json
此命令将从 localhost 请求你的应用程序，以及/swagger.json路径生成 API Swagger JSON 文件。
使用示例
假设我们有一个简单的 Foxify 应用，其根目录下有一个名为users.js的具有 CRUD 能力的路由。如以下代码。
-- -------------------- ---- -------
----- ----- - -
- --- -- ----- ---------
- --- -- ----- -------
- --- -- ----- -----------
--
----- ---------- - ----- -- -
--------------------- ----- ---- ----- -- -
----- -- - ---------------
----- ---- - --------------- -- ------- --- ----
-- ------- -
------ ----------------------
-
---------------
---
----------------- ----- ---- ----- -- -
----------------
---
------------------ ----- ---- ----- -- -
----- ---- - ---------
-----------------
----------------
---
--------------------- ----- ---- ----- -- -
----- -- - ---------------
----- --------- - -------------------- -- ------- --- ----
-- ---------- --- --- -
------ ----------------------
-
---------------- - ---------
----------------
---
------------------------ ----- ---- ----- -- -
----- -- - ---------------
----- --------- - -------------------- -- ------- --- ----
-- ---------- --- --- -
------ ----------------------
-
----------------------- ---
----------------
---
--
-------------- - -----------在上述代码中，有一个 users 数组，以及一个名为 userRoutes 的路由。 我们会使用该路由来对users数组执行 CRUD。 现在，我们将自动生成 Swagger 文档并自动生成客户端 SDK。
我们将假设您已经按照前面的步骤正确地配置了 Foxify Swagger Generator，并且您的路由文件保存在./routes/users.js路径下。在您的 Foxify 应用程序根目录下，运行以下命令：
curl http://localhost:3000/swagger.json > swagger.json
然后，安装 swagger-jsdoc 和 swagger-ui-express 依赖：
npm install swagger-ui-express npm install swagger-jsdoc
在您的app.js或index.js或其他入口文件中添加以下代码来呈现 Swagger UI：
-- -------------------- ---- -------
----- --------- - ------------------------------
----- ------------ - -------------------------
----- ---------------------- - ------------------------------------
----- ----------- - --------------------------
----- ------- - -
------------------ -
----- -
------ ----- -----
-------- --------
------------ ----- --- -------------
--
--------- ----
--
-------- ---------- ----- -------- ----
------ --------------------- ------ -- --- --- ------ ------
--
----- --- - ---------
-------------------------------------
-------------------- ---------------- ----------------------------------------
-----------------
---------------- -- -- ---------------- ------ ------- -- ---- --------然后，访问 http://localhost:3000/api-docs 将显示自动生成的 Swagger UI。通过 Swagger UI，您可以测试每一个 API 端点，以获得预期输出。
结论
通过本教程，您已经掌握了如何安装、配置和使用 Foxify Swagger Generator。 通过 Swagger UI，您将能够测试您的 API 的每一个端点，以获得预期的输出。你也将能够自动生成 Swagger.json 文件和客户端 SDK。
如果您需要在您的 Foxify 应用程序中使用 Swagger，那么使用 Foxify Swagger Generator 是一个极好的选择。它可以轻松生成文档和客户端 SDK，并帮助您快速步入开发和部署阶段。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600668f6d9381d61a3540eed