使用 Swagger JS NPM

Swagger JS NPM 是一个允许创建、编辑和执行 Swagger API 文档的工具。它基于 JavaScript 并可以与 Node.js 一起使用。此文将介绍 Swagger JS NPM 的主要功能和用法。

安装

安装 Swagger JS NPM 很容易，只需在命令行中运行以下命令：

npm install swagger-jsdoc swagger-ui-express express --save

上述命令会同时安装 Swagger JSDoc、Swagger UI Express 和 Express，这些是 Swagger JS NPM 必需的依赖项。

在 JavaScript 中使用 Swagger JS NPM

定义 API 文档

首先，我们需要定义我们的 API 文档。这可以通过写 JSDoc 注释来完成，例如：

/**
 * @swagger
 * /api/pets:
 *   get:
 *     summary: List all pets
 *     tags:
 *       - Pets
 *     responses:
 *       200:
 *         description: A list of pets.
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/Pet'
 */

这个 JSDoc 注释描述了一个 GET 请求，它将返回所有宠物的列表。Swagger JS NPM 将使用此注释来自动生成 API 文档。

生成 Swagger 规范

接下来，我们需要生成 Swagger 规范。这可以通过以下代码来完成：

const swaggerJSDoc = require('swagger-jsdoc');
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'],
};
const swaggerSpec = swaggerJSDoc(options);

在这个例子中，我们使用了 swagger-jsdoc 模块创建了 Swagger 规范，然后将其保存在 swaggerSpec 变量中。

将 Swagger UI 注入 Express 中

现在我们需要使用 Swagger UI 将生成的 Swagger 规范呈现为可交互的文档。这可以通过以下代码来完成：

const swaggerUi = require('swagger-ui-express');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

这个例子中，我们将 Swagger UI 挂载到 Express 的 /api-docs 路径上，并将生成的 Swagger 规范传递给 swaggerUi.setup() 函数。

现在，我们可以通过访问 /api-docs 路径来查看我们的 API 文档了！

结论

Swagger JS NPM 是一个使用方便的工具，可以帮助程序员创建交互式 API 文档。本文中介绍了 Swagger JS NPM 的基本用法，希望它能对你有所帮助。