npm 包 swagger-watcher 使用教程-JavaScript中文网-JavaScript教程资源分享门户

npm 包 swagger-watcher 使用教程

什么是 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。

-
  --------- -
    -
      -- ---------------
      ------- ------
    --
    -
      -- ----------
      --------- --------
    -
  -
-

swaggerFile

Swagger 规范文件的路径。如果文件发生变化，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