在前端开发中，接口文档是非常重要的，它对于后端开发者和前端开发者之间的协同开发起了很大的作用。本文介绍使用 Swagger 在 Hapi.js 中生成接口文档的方法，并提供详细的教程、示例代码以及实践指导。
Swagger 是什么？
Swagger（OpenAPI）是一个开放源代码的框架，用于设计，构建，文档化和消费 RESTful Web 服务。Swagger 描述了 RESTful Web 服务的结构，所有的 API 都有它们的终端（URL），以及输入和输出时应该使用的 HTTP 方法。Swagger 可以生成交互式 API 文档，这些文档在 API 定义更改时始终保持最新。
Hapi.js 是什么？
Hapi.js 是一个用于构建 Web 应用程序和服务的框架，它具有高度的可扩展性和插件化的架构。Hapi.js 和 Swagger 都是 Node.js 环境下的项目，都是经过广泛应用和社区验证的开源项目。
如何在 Hapi.js 中使用 Swagger 生成接口文档？
下面是在 Hapi.js 中使用 Swagger 生成接口文档的步骤：
步骤一：安装 Swagger
首先需要安装 Swagger，打开终端输入以下命令进行安装：
npm install swagger
步骤二：安装 swagger-ui-express 和 swagger-jsdoc
swagger-ui-express 提供了一个功能齐全的 Swagger UI。这个 UI 可以与您的 API 结合使用，以让您的 API 文档易于阅读和操作。swagger-jsdoc 是 Swagger 注释和 Node.js 框架之间的中间件。
npm install swagger-ui-express npm install swagger-jsdoc
步骤三：编写接口文档
编写接口文档是编写 Swagger 文档的核心。创建一个名为 swagger.json 的文件存储接口文档。下面是一个示例：
-- -------------------- ---- -------
-
---------- ------
------- -
-------------- ----- -- - ------ --- ------------- --- ------- ------- --- ------- ----
---------- --------
-------- ---- --------------
--
----------- ------
------- -
-
------- --------
-------------- ----------- ---- ------
-
--
---------- -
-------
-------
--
-------- -
--------- -
------ -
------- -
-------
--
-------------- -------- --- -------
----------- -
------------------
--
------------ -
------ -
-------------- ---- -------
--------- -
------- --------------------
-
-
-
-
-
--
-------------- -
------- -
------- ---------
----------- -
-------
-------
--
------------- -
------- -
------- ---------
---------- ----- ----
--
-------- -
------- ---------
--------- --------
---------- ----------------------
-
-
-
-
-在上面的示例文档中，我们定义了一个名为 users 的路由，它可以使用 HTTP GET 请求返回所有用户信息。通过 "/v1" 作为基础路径来定义所有的路由。
步骤四：创建路由
在 Hapi.js 中创建路由非常简单，下面我们来创建一个名为 user 的路由：
-- -------------------- ---- -------
----- ---- - ----------------------
----- ----- - --------------------------
----- ------ - -------------
----- -----
----- -----------
---
--------------------
----- ---------------
------------------- ------- -- ---------------------在上面的示例中，我们通过调用 server.route() 方法来注册路由中间件 users。
步骤五：显示接口文档
从步骤三中可以知道，我们定义了 "/users" 接口文档，我们需要在 Hapi.js 中创建一个 /swagger 路由，用来展示 Swagger UI 界面，并将 swagger.json 文件传递到 Swagger 中间件中。
-- -------------------- ---- -------
----- ---- - ----------------------
----- ----- - -----------------------
----- ------ - ------------------------
----- ----------- - ------------------------
----- ---- - ---------------------
----- ------ - -------------
----- -----
----- -----------
---
----- -------------- - -
----- -
------ ----- --- ---------------
-------- -------------
--
--
----- ------- - -
------
-------
-
------- ------------
-------- --------------
-
--
----- -------------------------
--------------
------- ------
----- ------------
-------- -
---------- -
----- --------
-
-
---
----- ---------------
------------------- ------- -- ---------------------在上面的示例中，我们使用 Hapi.js 提供的 Inert 和 Vision 插件，以及 hapi-swagger 插件生成 Swagger UI 界面并显示 swagger.json 的内容。
总结
在本文中，我们使用 Swagger 在 Hapi.js 中生成接口文档，并提供详细的教程、示例代码以及实践指导。希望这篇文章能够帮助你更好地利用 Swagger 来管理和维护接口文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/645a9c0b968c7c53b0cff4cc