随着前端开发的快速发展，越来越多的应用程序需要通过 API 与服务器进行通信。为了能够更好地协调和管理 API，Swagger 是一种流行的规范，用于描述和定义 API 的结构和操作。@ffra/swagger 是一个 npm 包，提供了一些工具和功能，可以帮助开发人员更轻松地实现 Swagger 规范。
安装 @ffra/swagger
使用 npm 安装 @ffra/swagger：
npm install @ffra/swagger
使用 @ffra/swagger
生成 Swagger 规范
@ffra/swagger 包含一个命令行工具 @ffra/swagger-cli，可以生成 Swagger 规范。使用以下命令启动命令行工具：
npx @ffra/swagger-cli
命令行工具将提示您输入 API 端点的位置和 Swagger 规范应该生成的目标位置。例如：
npx @ffra/swagger-cli init
输入 API 端点的位置，例如：
Enter the location of the API endpoint: http://localhost:3000/my-api
然后输入 Swagger 规范应该生成的目标位置，例如：
Enter the target location for the Swagger specification: ./swagger.json
最后，命令行工具将提示您输入 API 的标题、版本和描述。输入它们之后，@ffra/swagger-cli 将生成一个包含 API 信息的 Swagger 规范。
集成 Swagger UI
Swagger UI 是一个 Web 应用程序，用于呈现和测试 Swagger 规范。@ffra/swagger 包含一个名为 @ffra/swagger-ui 的 npm 包，可以使用以下命令安装它：
npm install @ffra/swagger-ui
要使用 Swagger UI，只需将以下代码添加到 HTML 文件中：
-- -------------------- ---- -------
--------- -----
------
------
--------- -----------
----- ---------------- --------------- -----------------------------------------------------------
-------
------
---- ----------------------
------- -------------------------------------------------------------------------
--------
------------- - ---------- -
----- -- - -----------------
---- -----------------
------- --------------
--
-
---------
-------
-------在 HTML 文件中，我们引入了 Swagger UI 的 CSS 和 JavaScript 文件，并创建一个 div 元素用于在其中呈现 Swagger UI。然后，我们使用 Swagger UI 的 JavaScript API 创建了一个 Swagger UI 实例，并将 Swagger 规范的 URL 设置为本地服务器上的 .json 文件。
Swagger 注释
使用 @ffra/swagger 时，可以使用 Swagger 注释来增强 API 中的文档。Swagger 注释是一些特殊的注释格式，它们包含了一些描述 API 路由、操作和模型的元数据信息。Swagger 注释可以帮助 Swagger 工具更好地理解和处理 API。
例如，下面是一个使用 Swagger 注释的 Express 路由示例：
-- -------------------- ---- ------- --- - -------- - ------ - ---- - -------- ------- --- ---- - ---------- - ---- - ------------ - ---- -- ---- - -------- - ----------------- - ------- - ----- ----- - ------ - ----- -------------------------- -- ---------------- -------- ----- ---- - -- --- ---
在上面的示例中，我们使用 Swagger 注释描述了一个路由和一个操作。注释的结构类似于 YAML 或 JSON，它们使用缩进和键值对来表示数据。在此示例中，我们使用 @swagger 标记来指定该注释是 Swagger 注释，然后定义了一个路径 /pets，并在其中定义了一个 HTTP GET 请求操作。我们还使用 summary 键来指定操作的摘要，responses 键来指定操作的响应，并使用 content 和 schema 来列出响应的数据结构。
总结
@ffra/swagger 是一个非常有用的工具，可以帮助前端开发人员更好地管理和使用 Swagger 规范。通过生成规范，集成 Swagger UI，使用 Swagger 注释，我们可以更轻松地实现可扩展且易于维护的 API。希望本教程对您有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60056c0181e8991b448e5b33