使用 Swagger 或 OpenAPI 记录 Node.js RESTful API

引言 🎯

大家好，欢迎来到今天的讲座！今天我们要探讨的是如何使用 Swagger 或 OpenAPI 来记录和管理你的 Node.js RESTful API。如果你曾经为你的 API 编写过文档，或者尝试过手动维护 API 文档，你一定知道这是一项多么繁琐且容易出错的任务。想象一下，每次修改 API 端点时，都要手动更新文档，还要确保所有参数、响应和错误代码都准确无误。听起来是不是很头疼？别担心，Swagger 和 OpenAPI 就是为了帮助你解决这些问题而生的！

在接下来的时间里，我们将一起深入探讨以下几个话题：

1. 什么是 Swagger 和 OpenAPI？
2. 为什么需要使用它们来记录 API？
3. 如何在 Node.js 项目中集成 Swagger 或 OpenAPI？
4. 如何定义 API 的路径、参数、请求体和响应？
5. 如何生成交互式的 API 文档？
6. 如何通过 Swagger UI 进行 API 测试？
7. 如何自动化 API 文档的生成和更新？
8. 最佳实践和常见问题

准备好了吗？让我们开始吧！🚀

---

1. 什么是 Swagger 和 OpenAPI？ 📜

1.1 Swagger 是什么？

Swagger 是一个非常流行的工具，用于设计、构建、记录和使用 RESTful API。它最初由 SmartBear 公司开发，后来被捐赠给了 Linux 基金会，并演变成了 OpenAPI 规范。Swagger 提供了一套完整的工具链，包括 API 设计、文档生成、测试和可视化界面。

Swagger 的核心是 OpenAPI 规范（以前称为 Swagger 规范），这是一个标准化的格式，用于描述 RESTful API。通过这个规范，你可以详细定义 API 的端点、请求参数、响应格式、认证方式等。最重要的是，Swagger 可以自动生成交互式的 API 文档，用户可以直接在浏览器中查看和测试 API。

1.2 OpenAPI 是什么？

OpenAPI（开放 API）是一个与语言无关的规范，用于描述 RESTful API。它定义了一种标准的 YAML 或 JSON 格式，用于描述 API 的各个部分。OpenAPI 规范不仅限于 Swagger，许多其他工具和框架也支持它。因此，使用 OpenAPI 规范编写的 API 文档可以轻松地与其他工具集成。

简单来说，OpenAPI 规范是一个“蓝图”，它描述了 API 的结构和行为。通过遵循这个规范，你可以确保你的 API 文档是清晰、一致且易于理解的。

1.3 Swagger 和 OpenAPI 的关系

Swagger 和 OpenAPI 是紧密相关的。Swagger 是一个具体的实现，而 OpenAPI 是一个规范。你可以把 OpenAPI 想象成一种“语言”，而 Swagger 是用这种语言编写的应用程序。Swagger 提供了工具和库，帮助你创建、管理和展示符合 OpenAPI 规范的 API 文档。

---

2. 为什么需要使用 Swagger 或 OpenAPI 来记录 API？ 🤔

2.1 手动编写 API 文档的痛点

在没有 Swagger 或 OpenAPI 的时代，开发者通常会手动编写 API 文档。这听起来很简单，但实际上却充满了挑战：

• 维护成本高：每次修改 API 端点或参数时，都需要手动更新文档。随着时间的推移，文档可能会变得过时，导致开发者和用户之间的误解。
• 容易出错：手动编写文档很容易遗漏某些细节，比如某个参数的类型、默认值或是否必填。这些小错误可能会导致客户端调用失败。
• 缺乏一致性：不同的开发者可能会使用不同的格式和风格来编写文档，导致文档不统一，难以阅读和维护。
• 无法实时测试：传统的 API 文档通常是静态的，用户无法直接在文档中测试 API。他们需要手动编写代码或使用 Postman 等工具来测试 API。

2.2 Swagger 和 OpenAPI 的优势

使用 Swagger 或 OpenAPI 来记录 API 可以解决上述问题，并带来以下优势：

• 自动生成文档：通过注释或配置文件，Swagger 可以自动生成 API 文档。这意味着你不需要手动编写每个端点的详细说明，减少了维护成本。
• 保持文档与代码同步：当你修改 API 时，Swagger 会自动更新文档，确保文档始终是最新的。这大大减少了文档过期的风险。
• 交互式文档：Swagger 提供了一个交互式的 UI（即 Swagger UI），用户可以直接在浏览器中查看 API 文档并进行测试。这使得开发者和用户可以更方便地理解和使用 API。
• 标准化的格式：OpenAPI 规范提供了一个标准化的格式，确保所有 API 文档的结构和内容都是一致的。这使得文档更易于阅读和理解。
• 支持多种工具和平台：由于 OpenAPI 是一个与语言无关的规范，许多工具和平台都支持它。你可以轻松地将 API 文档集成到 CI/CD 流程中，或者将其导出为不同格式的文档。

---

3. 如何在 Node.js 项目中集成 Swagger 或 OpenAPI？ 💻

3.1 安装必要的依赖

要在 Node.js 项目中使用 Swagger 或 OpenAPI，首先需要安装一些依赖包。我们可以使用 swagger-jsdoc 和 swagger-ui-express 这两个库来生成和展示 API 文档。

3.1.1 安装 swagger-jsdoc

swagger-jsdoc 是一个用于从 JSDoc 注释中生成 OpenAPI 规范的库。你可以通过 npm 安装它：

npm install swagger-jsdoc

3.1.2 安装 swagger-ui-express

swagger-ui-express 是一个 Express 中间件，用于在浏览器中展示 Swagger UI。你可以通过 npm 安装它：

npm install swagger-ui-express

3.2 配置 Swagger

接下来，我们需要配置 Swagger，告诉它如何生成 API 文档。我们可以通过创建一个 swaggerOptions 对象来指定 API 的基本信息和要扫描的文件路径。

const swaggerJSDoc = require('swagger-jsdoc');

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My Awesome API',
      version: '1.0.0',
      description: 'This is a sample API for demonstrating how to use Swagger with Node.js.',
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  apis: ['./routes/*.js'], // 指定要扫描的文件路径
};

const swaggerSpec = swaggerJSDoc(swaggerOptions);

3.3 设置 Swagger UI

现在我们已经生成了 API 文档，接下来需要设置 Swagger UI，以便用户可以在浏览器中查看和测试 API。我们可以通过 swagger-ui-express 来实现这一点。

const express = require('express');
const swaggerUi = require('swagger-ui-express');

const app = express();

// 将 Swagger UI 挂载到 /api-docs 路径
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// 启动服务器
app.listen(3000, () => {
  console.log('Server is running on http://localhost:3000');
});

3.4 添加 API 路由

为了使 Swagger 能够扫描到我们的 API 路由，我们需要在路由文件中添加 JSDoc 注释。例如，假设我们有一个简单的 GET 请求来获取用户信息：

/**
 * @swagger
 * /users:
 *   get:
 *     summary: 获取所有用户
 *     description: 返回所有用户的列表。
 *     responses:
 *       200:
 *         description: 成功返回用户列表
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */

app.get('/users', (req, res) => {
  res.json([
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' },
  ]);
});

在这个例子中，我们使用了 JSDoc 注释来描述 /users 路径的 GET 请求。@swagger 标签告诉 swagger-jsdoc 这是一个 API 端点，后面的注释则详细描述了请求的摘要、描述、响应等内容。

3.5 定义数据模型

为了让 API 文档更加完整，我们还可以定义数据模型。数据模型可以帮助用户了解 API 返回的数据结构。我们可以在 swaggerOptions 中定义 components，并在其中添加 schemas。

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My Awesome API',
      version: '1.0.0',
      description: 'This is a sample API for demonstrating how to use Swagger with Node.js.',
    },
    components: {
      schemas: {
        User: {
          type: 'object',
          properties: {
            id: {
              type: 'integer',
              description: '用户ID',
            },
            name: {
              type: 'string',
              description: '用户名',
            },
          },
        },
      },
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  apis: ['./routes/*.js'],
};

在这个例子中，我们定义了一个名为 User 的数据模型，它包含 id 和 name 两个属性。我们可以在 API 文档中引用这个模型，例如在上面的 /users 路径中，我们使用了 $ref: '#/components/schemas/User' 来引用 User 模型。

---

4. 如何定义 API 的路径、参数、请求体和响应？ 📝

4.1 定义 API 路径

API 路径是 API 的入口点，表示用户可以通过哪个 URL 访问 API。在 Swagger 中，我们可以使用 @swagger 标签来定义 API 路径。每个路径可以包含多个 HTTP 方法（如 GET、POST、PUT、DELETE 等），并且可以为每个方法定义不同的参数、请求体和响应。

4.1.1 GET 请求

GET 请求通常用于获取资源。我们可以通过 @swagger 标签来定义 GET 请求的路径、参数和响应。例如：

/**
 * @swagger
 * /users/{id}:
 *   get:
 *     summary: 获取指定用户的信息
 *     description: 根据用户ID返回用户信息。
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: 用户ID
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: 成功返回用户信息
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *       404:
 *         description: 用户不存在
 */

在这个例子中，我们定义了一个 /users/{id} 路径，它接受一个路径参数 id，并返回一个 User 对象。如果用户存在，返回 200 状态码和用户信息；如果用户不存在，返回 404 状态码。

4.1.2 POST 请求

POST 请求通常用于创建新资源。我们可以通过 @swagger 标签来定义 POST 请求的路径、请求体和响应。例如：

/**
 * @swagger
 * /users:
 *   post:
 *     summary: 创建新用户
 *     description: 创建一个新的用户并返回其信息。
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/NewUser'
 *     responses:
 *       201:
 *         description: 用户创建成功
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *       400:
 *         description: 请求体无效
 */

在这个例子中，我们定义了一个 /users 路径，它接受一个 JSON 格式的请求体，包含 NewUser 模型中的字段。如果请求成功，返回 201 状态码和新创建的用户信息；如果请求体无效，返回 400 状态码。

4.2 定义参数

参数是 API 请求中传递给服务器的数据。在 Swagger 中，我们可以为每个 API 端点定义不同类型的参数，包括路径参数、查询参数、请求头和请求体。

4.2.1 路径参数

路径参数是 URL 中的一部分，通常用于标识特定的资源。我们可以通过 parameters 字段来定义路径参数。例如：

parameters:
  - in: path
    name: id
    required: true
    description: 用户ID
    schema:
      type: integer

4.2.2 查询参数

查询参数是 URL 中的键值对，通常用于过滤或分页。我们可以通过 parameters 字段来定义查询参数。例如：

parameters:
  - in: query
    name: page
    description: 分页参数
    schema:
      type: integer
      default: 1

4.2.3 请求头

请求头是 HTTP 请求中的一部分，通常用于传递认证信息或其他元数据。我们可以通过 parameters 字段来定义请求头。例如：

parameters:
  - in: header
    name: Authorization
    description: Bearer Token
    required: true
    schema:
      type: string

4.2.4 请求体

请求体是 HTTP 请求中传递的数据，通常用于创建或更新资源。我们可以通过 requestBody 字段来定义请求体。例如：

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/NewUser'

4.3 定义响应

响应是 API 返回给客户端的数据。在 Swagger 中，我们可以为每个 API 端点定义不同的响应状态码和响应体。例如：

responses:
  200:
    description: 成功返回用户信息
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
  404:
    description: 用户不存在

在这个例子中，我们定义了两个响应：200 表示成功返回用户信息，404 表示用户不存在。

---

5. 如何生成交互式的 API 文档？ 📚

一旦我们完成了 API 的定义，Swagger 就可以自动生成交互式的 API 文档。通过 swagger-ui-express，我们可以在浏览器中访问 /api-docs 路径，查看 API 文档并进行测试。

5.1 访问 API 文档

启动服务器后，打开浏览器并访问 http://localhost:3000/api-docs，你将看到一个交互式的 API 文档页面。这个页面展示了所有已定义的 API 端点，并提供了详细的说明和示例。

5.2 测试 API

在 Swagger UI 中，你可以直接测试 API。点击任意一个 API 端点，填写必要的参数，然后点击“Try it out”按钮。Swagger 会自动发送 HTTP 请求，并显示响应结果。你还可以查看请求的原始数据和响应的详细信息。

5.3 导出 API 文档

如果你想将 API 文档导出为 JSON 或 YAML 文件，可以在 Swagger UI 中点击右上角的“Export”按钮。你可以选择导出 OpenAPI 3.0 规范的 JSON 或 YAML 文件，或者导出 Postman 集合。

---

6. 如何通过 Swagger UI 进行 API 测试？ 🔍

Swagger UI 不仅是一个文档生成工具，它还提供了一个强大的 API 测试功能。通过 Swagger UI，你可以在浏览器中直接测试 API，而无需编写任何代码。这对于开发者和测试人员来说非常方便。

6.1 测试 GET 请求

假设我们有一个 /users/{id} 路径，用于获取指定用户的详细信息。我们可以在 Swagger UI 中点击这个路径，填写 id 参数，然后点击“Try it out”按钮。Swagger 会自动发送 GET 请求，并显示响应结果。

6.2 测试 POST 请求

假设我们有一个 /users 路径，用于创建新用户。我们可以在 Swagger UI 中点击这个路径，填写请求体中的 name 和 email 字段，然后点击“Try it out”按钮。Swagger 会自动发送 POST 请求，并显示响应结果。

6.3 测试 PUT 和 DELETE 请求

同样，你也可以使用 Swagger UI 来测试 PUT 和 DELETE 请求。只需选择相应的 HTTP 方法，填写必要的参数，然后点击“Try it out”按钮即可。

6.4 查看请求和响应

在 Swagger UI 中，你可以查看每个请求的详细信息，包括请求头、请求体、响应头和响应体。这对于调试 API 非常有帮助。

---

7. 如何自动化 API 文档的生成和更新？ ⚙️

手动更新 API 文档可能会非常繁琐，尤其是在项目规模较大时。幸运的是，我们可以使用一些工具来自动化 API 文档的生成和更新。

7.1 使用 swagger-autogen

swagger-autogen 是一个用于自动生成 Swagger 文档的工具。它可以根据你的 Express 应用程序自动生成 OpenAPI 规范，并将其保存为 JSON 或 YAML 文件。

7.1.1 安装 swagger-autogen

你可以通过 npm 安装 swagger-autogen：

npm install swagger-autogen --save-dev

7.1.2 生成 API 文档

在项目的根目录下创建一个 swaggerAuto.ts 文件，并编写以下代码：

import swaggerAutogen from 'swagger-autogen';

const outputFile = './swagger_output.json';
const endpointsFiles = ['./routes/*.js'];

const doc = {
  info: {
    title: 'My Awesome API',
    version: '1.0.0',
    description: 'This is a sample API for demonstrating how to use Swagger with Node.js.',
  },
  servers: [
    {
      url: 'http://localhost:3000',
    },
  ],
};

swaggerAutogen(outputFile, endpointsFiles, doc);

运行 node swaggerAuto.ts，swagger-autogen 会自动生成 swagger_output.json 文件，并将其保存到项目的根目录下。

7.2 使用 CI/CD 工具

你还可以将 API 文档的生成和更新集成到 CI/CD 流程中。例如，你可以在 GitHub Actions 或 GitLab CI 中添加一个步骤，在每次代码提交时自动生成最新的 API 文档，并将其部署到静态网站托管服务（如 Netlify 或 Vercel）。

---

8. 最佳实践和常见问题 📝

8.1 最佳实践

• 保持 API 文档与代码同步：确保每次修改 API 时，都及时更新 API 文档。可以使用 swagger-jsdoc 或 swagger-autogen 来自动生成文档，减少手动维护的成本。
• 使用标准化的命名约定：为 API 路径、参数和响应使用一致的命名约定，这样可以让文档更易于理解和维护。
• 为每个 API 端点编写详细的说明：不仅要描述 API 的功能，还要解释每个参数的含义、请求体的结构以及可能的响应状态码。
• 使用数据模型：为复杂的 API 响应定义数据模型，这样可以让用户更清楚地了解 API 返回的数据结构。
• 定期审查 API 文档：即使使用了自动化工具，仍然需要定期审查 API 文档，确保其准确性和完整性。

8.2 常见问题

8.2.1 Swagger UI 无法加载

如果你在访问 Swagger UI 时遇到问题，可能是由于路径配置不正确。请确保 swagger-ui-express 的挂载路径与你的 API 路径不冲突。你可以在 app.use() 中指定不同的路径，例如 /docs 或 /api-docs。

8.2.2 API 文档未更新

如果你修改了 API 但文档没有更新，可能是由于 swagger-jsdoc 未能正确扫描到新的 API 路径。请检查 apis 字段中的路径是否正确，并确保所有 API 路由都包含了 JSDoc 注释。

8.2.3 请求体验证失败

如果你在测试 API 时遇到请求体验证失败的问题，可能是由于请求体的格式不符合 API 的预期。请确保请求体中的字段名称和类型与 API 文档中定义的一致。

---

结语 🎉

恭喜你，终于走到了文章的最后！通过今天的学习，你应该已经掌握了如何使用 Swagger 或 OpenAPI 来记录和管理 Node.js RESTful API。无论你是刚开始接触 API 文档，还是已经在使用 Swagger，希望这篇文章能够为你提供一些有价值的见解和技巧。

记住，API 文档不仅仅是给用户看的，它也是开发者之间沟通的重要桥梁。通过使用 Swagger 和 OpenAPI，你可以让 API 文档变得更加清晰、一致和易于维护。祝你在未来的 API 开发中一帆风顺！🌟

如果有任何问题或建议，欢迎随时提问。感谢你的聆听，再见！👋