Swagger/OpenAPI 生成工具与库 — JavaScript (Node.js)

Swagger/OpenAPI 生成工具 — JavaScript (Node.js)

在 Node.js 上开发 REST API 时，关键任务之一是创建清晰且最新的文档。Swagger（现为 OpenAPI）已成为描述 API 的事实标准。本文将介绍在 JavaScript (Node.js) 项目中自动生成 OpenAPI 规范的主要工具。

什么是 OpenAPI，为什么要生成它？

OpenAPI 是一种用于以 JSON 或 YAML 格式描述 RESTful API 的规范。它允许：

• 自动创建交互式文档（Swagger UI）
• 为不同语言生成客户端 SDK
• 验证请求和响应
• 简化团队之间的集成

手动编写规范是一项耗时且容易过时的工作。因此，Node.js 开发了从代码生成 OpenAPI 的工具。

Node.js 中生成 OpenAPI 的主要工具

1. swagger-jsdoc

最流行的库，它解析代码中的 JSDoc 注释并将其转换为 OpenAPI 规范。通过 npm 安装：

npm install swagger-jsdoc swagger-ui-express

与 Express 一起使用的示例：

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

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

const swaggerSpec = swaggerJsdoc(options);app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// 带注释的路由示例/** * @openapi * /users: *   get: *     summary: 获取用户列表 *     tags: [Users] *     responses: *       200: *         description: 成功响应 *         content: *           application/json: *             schema: *               type: array *               items: *                 $ref: '#/components/schemas/User' */app.get('/users', (req, res) => {  res.json([{ id: 1, name: '伊万' }]);});

app.listen(3000);

2. swagger-autogen

更现代的替代方案，它基于注释中的注解生成规范，并自动确定数据类型。安装：

npm install swagger-autogen

生成脚本示例：

const swaggerAutogen = require('swagger-autogen')();

const doc = {  info: {    title: '我的 API',    description: 'API 描述'  },  host: 'localhost:3000',  schemes: ['http']};

const outputFile = './swagger-output.json';const endpointsFiles = ['./app.js']; // 包含路由的主文件

swaggerAutogen(outputFile, endpointsFiles, doc).then(() => {  require('./app.js'); // 生成后启动服务器});

在路由中只需添加注释：

// #swagger.tags = ['Users']// #swagger.description = '用于获取用户的端点'app.get('/users', (req, res) => {  // #swagger.responses[200] = { description: '用户列表' }  res.json([{ id: 1, name: '安娜' }]);});

3. express-oas-generator

一个拦截请求并根据实际数据自动构建 OpenAPI 规范的库。适用于原型：

npm install express-oas-generator

const express = require('express');const expressOasGenerator = require('express-oas-generator');const app = express();

expressOasGenerator.init(app, {}); // 初始化

app.get('/products', (req, res) => {  res.json