什么是 swagger-watcher?
swagger-watcher 是一个 Node.js 应用程序，可以通过监视和更新自己定义的 Swagger 规范来生成和维护 API 文档。
安装和使用
安装
npm install -g swagger-watcher
使用
在使用之前，首先需要设置一个配置文件（以 config.json 为例）。
-- -------------------- ---- -------
-
------- -----
--------- -
-
------- ------
-
--
-------------- ----------------
-port: 服务端口号filter: 过滤器，用于排除不需要监视的paths或者methods。swaggerFile: Swagger 规范文件的路径。
接下来，我们可以运行 swagger-watcher。
swagger-watcher --conf ./config.json
现在我们可以使用浏览器访问 http://localhost:8080 来查看自动生成的文档。
细节解析
配置文件
port服务端口号，默认值为
8080。filter过滤器，用于排除不需要监视的 paths 或者 methods。
-- -------------------- ---- ------- - --------- - - -- --------------- ------- ------ -- - -- ---------- --------- -------- - - -swaggerFileSwagger 规范文件的路径。如果文件发生变化，
swagger-watcher将自动重新生成 API 文档。
自定义标题
默认情况下，标题将是 Swagger 规范的 title 字段。我们也可以用 title 字段来自定义标题。
-- -------------------- ---- -------
-
-------- --------
------- -----
--------- -
-
------- ------
-
--
-------------- ----------------
-过滤器详解
过滤器可以用来排除某些 paths 或者 methods。
-- -------------------- ---- -------
-
--------- -
-
-- ---------------
------- ------
--
-
-- ----------
--------- --------
-
-
-filter 是一个数组，每个数组项都是一个对象。对象可以包含两个属性：
name: path 的名字method: method 的名字
同时，name 和 method 可以使用通配符：
*：匹配任意的名字或者方法。**：匹配任意路径和方法。
过滤规则会先根据 name 进行过滤，接着才是 method。也就是说，如果一个 path 的名字匹配了，但是 method 不匹配，这个 path 仍然会被包含在文档中。
示例
我们可以使用 swagger-watcher 生成文档。这里我们使用 https://petstore.swagger.io/v2/swagger.json 作为 Swagger 规范文件。
安装
npm install -g swagger-watcher
运行
swagger-watcher --port=3000 --swaggerFile=https://petstore.swagger.io/v2/swagger.json
结果
现在可以在浏览器中查看自动生成的文档：http://localhost:3000。
总结
本文简要介绍了 swagger-watcher 的功能和使用方法，并对其中的细节进行了解析和详细的说明。希望读者可以通过本文对 swagger-watcher 有一个更全面、了解。在实际项目中，使用 swagger-watcher 可以大大简化文档的维护，提高文档的实时性，为项目管理带来不少的便利。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/80397