在Node.js开发中，我们经常需要编写RESTful API，并为其编写在线文档，以方便后期维护和协作开发。Swagger是一种用于编写API在线文档、交互式API测试和API元数据的规范与工具，它可以生成高质量的在线文档，可读性强，并且支持对API的测试和交互，这对于开发和测试都非常有利。在本文中，我们将学习如何使用Swagger UI来展示和交互API文档，并为大家提供示例代码以指导您完成相关的开发工作。
准备工作
在开始使用Swagger UI之前，我们需要先准备一些必要的资源。首先，我们需要安装node.js，如果您已经安装了Node.js，请确保您的版本是6.0及以上的。其次，我们需要安装Swagger UI。可以通过在命令行中使用以下命令进行安装。
--- ------- ----------
完成以上步骤之后，我们要为API编写Swagger规范，以便Swagger UI可以使用它来生成在线文档。
编写Swagger规范
Swagger规范通常是一个json格式的文件，其格式与API的类型和参数相关。swagger.json是一个包含两个API的简单示例，我们将使用它来进行API交互和测试：
-
---------- ------
------- -
-------- -------- ------ -----
-------------- ----- -- - ------ --- ---- ------------ ----- --------------- -- ---------
---------- -----
--
------- -----------------
----------- -------
---------- -
------
--
----------- -
------------------
--
----------- -
------------------
--
-------- -
--------- -
------ -
------- -
-------
--
---------- -------- --- --- ----- -- --- ---- -------
------------ -
------ -
-------------- -- ---- -- -------
--------- -
------- --------
-------- -
------- --------------------
-
-
-
-
-
-
--
-------------- -
------- -
------- ---------
------------- -
----- -
------- ----------
--------- -------
--
------- -
------- --------
-
-
-
-
-上面的示例文件包含的信息包括API的主机和基本路径，API的请求响应格式、数据类型和返回值。因此，我们可以看到设置了API的主机为localhost:3000，基本路径为/api，并定义了一个返回所有用户的API。
使用Swagger UI来展示API文档
我们现在可以开始使用Swagger UI了，这里是一些关于如何使用Swagger UI来展示API文档的基本步骤。
步骤1：创建一个HTML文件
创建一个新的HTML文件，并在文件中添加以下代码：
--------- -----
----- ----------
------
----- ----------------
-------------- ----------
----- ---------------- --------------- ---------------------------------------------------- -
-------
------
---- ----------------------
------- -------------------------------------------------------------------
------- ------------------------------------------------------------------------------
--------
------------- - -------- -- -
-- ----- ------- -- ---- ------
----- -- - -----------------
------ ----------------
--------- --------------
------------ -----
-------- -
-----------------------------
-------------------------
--
-------- -
-----------------------------------
--
------- ------------------
--
-- --- ------- -- ---- ------
--------- - --
-
---------
-------
-------其中，上述代码中引入了样式表、相关的js文件和生成文档的配置信息，这里使用了本地的swagger.json文件。
步骤2：运行服务器
在命令行中输入以下命令启动服务器：
---- ---------
其中server.js是Node.js服务器文件的名称，如果没有指定则使用默认名称。在这一步中，我们必须保证我们的swagger.json文件在启动的服务器目录中。
步骤3：打开浏览器
在浏览器中输入以下地址：
---------------------
此时您将看到Swagger UI生成的在线API文档。
结论
本文主要介绍了如何使用Swagger UI来展示和交互API文档，并为您提供了一个简单的示例，希望对您的开发工作有所帮助。您可以通过阅读官方文档来更深入地了解Swagger API规范。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/671b539a9babaf620faabe60