Swagger/OpenAPI 生成用于 Node.js (JavaScript)：工具与示例

Swagger/OpenAPI 生成用于 Node.js (JavaScript)

在开发基于 Node.js 的现代 Web 应用程序时，关键任务之一是为 API 创建清晰且最新的文档。Swagger (OpenAPI) 是一种描述 RESTful 接口的标准，它允许自动生成交互式文档、测试请求并维护客户端与服务器之间的契约。在本文中，我们将介绍如何使用流行的库为 Node.js 应用程序配置 Swagger/OpenAPI 文档的生成。

什么是 Swagger 和 OpenAPI？

OpenAPI 规范（以前称为 Swagger 规范）是一种描述 HTTP API 的正式标准。它允许：

• 定义端点、方法、参数和响应类型。
• 自动生成客户端 SDK。
• 创建交互式文档（Swagger UI）。
• 验证请求和响应。

对于 Node.js，有几个库可以简化 OpenAPI 的集成。我们来看两个最流行的：swagger-jsdoc 和 swagger-ui-express。

用于在 Node.js 中生成 Swagger 的库

主要工具：

• swagger-jsdoc — 解析代码中的 JSDoc 注释，并从中生成 OpenAPI 规范。
• swagger-ui-express — 将生成的规范显示为交互式网页。
• @nestjs/swagger（如果使用 NestJS）— 用于自动生成的装饰器。

我们将重点介绍用于 Express.js 的 swagger-jsdoc + swagger-ui-express 组合。

安装与配置

通过 npm 安装必要的包：

npm install swagger-jsdoc swagger-ui-express

创建一个包含基本配置的 swagger.js 文件：

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

const options = {    definition: {        openapi: '3.0.0',        info: {            title: 'My Node.js API',            version: '1.0.0',            description: '带有自动生成 Swagger 的示例 API',        },        servers: [            { url: 'http://localhost:3000' },        ],    },    apis: ['./routes/*.js'], // 包含端点的文件路径};

const swaggerSpec = swaggerJsdoc(options);

module.exports = { swaggerUi, swaggerSpec };

为端点添加 JSDoc 注释

现在，在您的路由文件中（例如 routes/users.js），添加 OpenAPI 格式的注释：

/** * @openapi * /users: *   get: *     summary: 获取用户列表 *     tags: [Users] *     parameters: *       - in: query *         name: limit *         schema: *           type: integer *         description: 用户数量（默认 10） *     responses: *       200: *         description: 用户列表 *         content: *           application/json: *             schema: *               type: array *               items: *                 $ref: '#/components/schemas/User' */router.get('/users', async (req, res) => {    const users = await getUsers(req.query.limit || 10);    res.json(users);});

类似地定义数据模型：

/** * @openapi * components: *   schemas: *     User: *       type: object *       properties: *         id: *           type: integer *         name: *           type: string *         email: *           type: string */

将 Swagger UI 连接到 Express

在应用程序的主文件（app.js 或 index.js）中添加：

const express = require('express');const { swaggerUi,