在使用 Node.js 后端框架 sails 开发 web 应用时，我们经常需要编写 API 接口，而编写文档是很耗费时间的一件事情，swagger 是一个 RESTful API 的文档生成工具，它能够根据代码自动生成文档，并提供了一些文档展现和管理的功能。
sails-swagger-pp 是 sails 的一个对接 swagger 的第三方库，它不仅能够自动生成 swagger 风格的 API 文档，还提供了一些额外的功能，比如完善的参数校验和请求响应的自动化测试等。这篇文章将详细介绍如何使用 sails-swagger-pp 库来提高工作效率。
安装
首先，我们需要在 sails 项目中安装 sails-swagger-pp 包。在终端中进入 sails 项目的根目录，然后执行以下命令：
npm install sails-swagger-pp --save
添加配置
安装完 sails-swagger-pp 包后，我们需要在 sails 项目的配置文件中添加相关配置。打开 config/swagger.js 文件，并输入以下内容：
-- -------------------- ---- -------
---------------------- - -
---- ----------------------
--------- ----------
----- -
------ ---- ---------------
-------- --------
--
----- --------------------------- ----------------------
------ -
------------- --------------------------------------
--
--在这段配置中，我们指定了：
pkg：指定项目的 package.json 文件，用于获取项目的名称和版本号。basePath：API 的根路径。info：API 文档的基本信息，包括标题和版本号。apis：文档生成器扫描的文件夹目录。'api/controllers/**/*.js'指定了扫描所有在api/controllers文件夹下的 JS 文件，而'api/models/**/*.js'指定了扫描所有在api/models文件夹下的 JS 文件。tools：swagger 的一些工具和配置项。在这个配置中，我们指定了 swagger-validator 的 URL。
在控制器中添加 swagger 注解
接下来，我们需要在 sails 的控制器中添加 swagger 注解。下面是一个例子：
-- -------------------- ---- -------
-------------- - -
------------- ------- - --- ------
------------ ------- - --- -------
------- -
------ -
----- ---------
--------- -----
------------ ------ -- --- --- ------
--
----- -
----- ---------
--------- -----
------------ ----- -- --- --- ------
--
--
------ -
-------- -
------------- ---
------------ ----- ------- --------------
--
-------- -
------------- -------------
------------ ---- -------- ---- -- ---------
--
--
-- ------- --
-------- -
-------- ---------
-------- ------- - --- ------
------------ ------- - --- ---- ---- --- -------- -------
--------- ---------------------
----- ---------
---------- -
---- -
------------ ----- ------- ---------------
--
---- -
------------ ---- -------- ---- -- ----------
------- -
----- ---------
----------- -
-------- -
----- ---------
--
------- -
----- --------
------ -
----- ---------
--
--
--
--
--
--
--
--- ----- -------- -------- ------ -
-- ----
------ ----------------
--
--在这段代码中，我们使用了 sails-swagger-pp 提供的 swagger 注解来描述 API 接口的元数据，包括 API 的请求方法、请求参数、响应类型和成功或者失败情况等。
启动 sails 项目并生成文档
最后，我们需要启动 sails 项目，并生成 swagger 风格的文档。在控制台中输入以下命令：
sails lift
启动项目后，在浏览器中打开 http://localhost:1337/api-docs，就可以访问到我们刚刚生成的 API 文档了。可以看到我们编写的注解会被自动解析为 API 文档中的元数据，方便其他人查看和调用。
至此，我们已经完成了 sails-swagger-pp 库的使用教程。通过使用该库，我们可以大大提高编写接口文档的效率，让我们的开发工作变得更加高效和优雅！
示例代码
以下是一个完整的 API 控制器的示例代码：
-- -------------------- ---- -------
---
- --------------
-
- ------------ -- ----------- ------- --- -------- -------- ---------
--
-------------- - -
------------- ------- - --- ------
------------ ------- - --- -------
------- -
------ -
----- ---------
--------- -----
------------ ------ -- --- --- ------
--
----- -
----- ---------
--------- -----
------------ ----- -- --- --- ------
--
--
------ -
-------- -
------------- ---
------------ ----- ------- --------------
--
-------- -
------------- -------------
------------ ---- -------- ---- -- ---------
--
--
-- ------- --
-------- -
-------- ---------
-------- ------- - --- ------
------------ ------- - --- ---- ---- --- -------- -------
--------- ---------------------
----- ---------
---------- -
---- -
------------ ----- ------- ---------------
--
---- -
------------ ---- -------- ---- -- ----------
------- -
----- ---------
----------- -
-------- -
----- ---------
--
------- -
----- --------
------ -
----- ---------
--
--
--
--
--
--
--
--- ----- -------- -------- ------ -
-- ----
----- -------- - ----- ---------------------------------
-- ----
----- ---- - ----- -------------
----- ------------
------ -------------
--------- ---------
--------------
- ------------------------------------------------------------------------------ --------
------------------------------------------------------------------------------------------------------------------------