Fastify 是一个高效、低开销且高度可定制的 Node.js Web 框架。和其他框架比起来，Fastify 有着更好的性能和稳定性表现。而 Swagger UI 是一个流行的，使用 OpenAPI 规范在 Web 上渲染交互式 API 文档的工具。Fastify 兼容 OpenAPI 规范，支持使用 Swagger UI 展示 API 文档，为开发者提供了更好的文档体验。在本文中，我们将学习如何使用 Fastify 和 Swagger UI 来展示 API 文档。
环境准备
本文将引用 Fastify 和 Swagger UI 的两个 npm 包，需要安装 Node.js 和 npm，你可以从官方网站 https://nodejs.org/ 下载并安装。
安装完毕后，请在命令行中输入以下命令安装 Fastify 和 Swagger UI：
npm i fastify swagger-ui-fastify
创建 Fastify 应用
首先，我们需要创建一个基本的 Fastify 应用，代码如下：
const fastify = require('fastify')();
fastify.listen(3000, (err, address) => {
if (err) throw err;
console.log(`Server listening on ${address}`);
});以上代码创建了一个 Fastify 实例，并在端口 3000 上启动了服务器。在本例中，我们将以该实例为基础构建 Swagger UI。
定义 API 路由
接下来，我们需要定义一些 API 路由。代码如下：
-- -------------------- ---- -------
-------------------- ----- ------ -- -
-------------------
---
------------------------- ----- ------ -- -
----- - -- - - -----------
------------
---
----- ---- -------
------ ------------------
---
---以上代码定义了两个路由。第一个路由回应 GET /ping 请求，并返回字符串 'pong'。第二个路由回应 GET /users/:id 请求，并返回一个关于 Tom Brady 的简单对象。在实际应用中，这些路由需要更加完善和复杂。
配置 Swagger UI
Swagger UI 需要一些元数据来渲染出 API 文档的格式。可以通过在项目代码中定义一个 JSON 文件来实现。在本例中，我们将创建一个名为 swagger.json 的文件，并将其放置在项目的根目录下。文件内容如下：
-- -------------------- ---- -------
-
---------- --------
------- -
-------- ------------------ ------- -----
---------- --------
-------------- -- ------------- -- ------- --- ------- ---
--
---------- -
-
------ ------------------------
-------------- ------ -------
-
--
-------- -
-------- -
------ -
-------------- -- ------ ------ -------
------------ -
------ -
-------------- ----------- ----------
---------- -
------------------- -
--------- -
------- --------
-
-
-
-
-
-
--
-------------- -
------ -
-------------- --------- - ------
------------- -
-
------- -----
----- -------
----------- -----
-------------- ----- ----
--------- -
------- ---------
-
-
--
------------ -
------ -
-------------- ----------- ----------
---------- -
------------------- -
--------- -
------- ---------
------------- -
----- -
------- ---------
--
------- -
------- --------
--
-------- -
------- --------
-
-
-
-
-
-
-
-
-
-
-以上文件定义了一些 OpenAPI 元数据，包括 API 的元数据以及各个端点的定义。
然后，我们需要修改 Fastify 应用，以支持 Swagger UI。代码如下：
-- -------------------- ---- -------
----- ------- - ---------------------
----- ------- - ------------------------------
----- ----------- - --------------------------
------------------------- -
-------- ------------
------- --------
---
-------------------- ----- ------ -- -
-------------------
---
------------------------- ----- ------ -- -
----- - -- - - -----------
------------
---
----- ---- -------
------ ------------------
---
---
-------------------- ----- -------- -- -
-- ----- ----- ----
------------------- --------- -- -------------
---以上代码将 swagger.json 文件作为元数据载入 Swagger UI 插件。在注册 swagger-ui-fastify 插件时，我们指定了一些选项来控制 UI 的渲染行为。具体而言，我们指定了 Swagger UI 的路径前缀为 /docs，以及元数据文件的位置。在定义路由时，我们不再需要修改其响应的格式和结构，因为 Swagger UI 将以元数据文件为基础自动生成 API 文档。
启动服务器和访问 Swagger UI
在本例中，我们将 Fastify 应用运行在本地计算机上的端口 3000，因此可以使用浏览器访问 http://localhost:3000/docs 来查看 Swagger UI。你应该会看到 Swagger UI 中呈现的完整的 API 文档信息。你可以浏览所有的 API 端点，测试它们，甚至查看 Curl 命令以及请求和响应数据。当然，具体的呈现方式与 UI 的版本和配置相关，可能有所不同。
总结
本文中介绍了如何在 Fastify 应用中使用 Swagger UI 来展示 API 文档。在实际应用中，你会发现使用 Swagger UI 来记录和检查 API 端点是开发过程中很有帮助的。在你的自动化测试-suite 中引入 Swagger UI 就能使测试结果更加易懂，并让新加入开发者更快掌握和理解项目的 API 结构。本文所使用的代码也提供了一个可以扩展的开发基础，让你能够在自己的应用中集成 Swagger UI，并搭建你自己的文档材料。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/65a21918add4f0e0ffa297d4