在前端开发中，API 文档是非常重要的一部分。它能够帮助开发者更好地了解后端接口的使用方式和参数要求，从而减少开发过程中的沟通成本和出错概率。而 Fastify 框架则是近年来备受关注的一款高性能 Node.js Web 框架，它的灵活性和易用性都非常出色。本文将介绍如何在 Fastify 框架中使用 Hapi-swagger 插件来自动生成 API 文档。
安装 Hapi-swagger 插件
在使用 Hapi-swagger 插件之前，我们需要先安装它。可以使用 npm 命令来进行安装：
npm install fastify-swagger hapi-swagger
其中，fastify-swagger 是 Hapi-swagger 的 Fastify 版本，而 hapi-swagger 则是 Hapi.js 框架中的 Swagger 插件。
配置 Fastify 插件
在安装完 Hapi-swagger 插件之后，我们需要在 Fastify 中进行配置。在 Fastify 的启动文件中，我们需要添加以下代码：
-- -------------------- ---- -------
----- ------- - ---------------------
----- ------- - ---------------------------
------------------------- -
------------ -----------------
-------- -
----- -
------ ---- ---------------
------------ -------- --- ---------------
-------- -------
--
----- -----------------
-------- ---------
--------- ---------------------
--------- ---------------------
----- -
- ----- ------- ------------ ----- ------- ----------- --
- ----- ------- ------------ ----- ------- ----------- -
-
--
------------ ----
---
-------------------- ----- -------- -- -
-- ----- -
-------------------
----------------
-
------------------- --------- -- -------------
---在上面的代码中，我们首先引入了 Fastify 和 Hapi-swagger 插件。然后，我们通过 fastify.register() 方法来注册 Hapi-swagger 插件，并对 Swagger 进行了一些配置。其中，routePrefix 属性用于指定 Swagger 文档的路由前缀，swagger 属性用于配置 Swagger 的一些参数，exposeRoute 属性用于指定是否将 Swagger 文档的路由暴露出来。
编写 API 文档
在完成了配置之后，我们就可以开始编写 API 文档了。在 Fastify 中，我们可以通过 decorators 来为路由添加一些元数据，例如路由名称、路由描述、路由参数等。这些元数据可以被 Hapi-swagger 插件自动解析，并生成对应的 API 文档。
例如，下面是一个简单的用户注册接口：
-- -------------------- ---- -------
---------------------- -
------- -
----- -
----- ---------
----------- -
----- - ----- -------- --
------ - ----- -------- --
--------- - ----- -------- -
--
--------- -------- -------- -----------
--
--------- -
---- -
----- ---------
----------- -
--- - ----- -------- --
----- - ----- -------- --
------ - ----- -------- -
-
-
--
----- ---------
------------ ------- - --- -----
-
-- ----- ------ -- -
-- --------
---在上面的代码中，我们使用了 schema 属性来为路由添加元数据。其中，body 属性指定了请求体的参数要求，response 属性指定了响应体的参数要求，tags 属性指定了路由所属的标签，description 属性指定了路由的描述。这些元数据将被 Hapi-swagger 插件自动解析，从而生成对应的 API 文档。
查看 API 文档
在完成了 API 文档的编写之后，我们就可以在浏览器中查看生成的文档了。只需要访问 http://localhost:3000/documentation 即可。在 Swagger 文档中，我们可以查看所有的路由、路由的描述、参数要求、响应体要求等信息。同时，我们还可以在 Swagger 文档中进行测试，以便更好地理解路由的使用方式。
总结
本文介绍了如何在 Fastify 框架中使用 Hapi-swagger 插件来自动生成 API 文档。通过使用 Hapi-swagger 插件，我们可以轻松地为路由添加元数据，并生成对应的 API 文档。同时，Swagger 文档还可以在浏览器中进行查看和测试，从而更好地了解后端接口的使用方式和参数要求。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/65115f5695b1f8cacd9d6b10