使用swagger-jsdoc自动生成OpenAPI文档的最佳实践-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00556/article/details/148967623

使用swagger-jsdoc自动生成OpenAPI文档的最佳实践

项目概述

swagger-jsdoc是一个强大的Node.js库，它能够通过解析JSDoc注释自动生成符合OpenAPI规范（原Swagger规范）的API文档。这个工具完美结合了代码注释与文档生成，让开发者可以在编写代码的同时维护API文档，确保文档与代码保持同步。

核心功能

JSDoc注释解析：识别代码中的@openapi或@swagger标签
多规范支持：支持OpenAPI 3.x、Swagger 2和AsyncAPI 2.0规范
自动生成：将注释转换为完整的OpenAPI规范文档
验证机制：可配置是否在解析错误时抛出异常

快速入门

安装

npm install swagger-jsdoc --save
# 或
yarn add swagger-jsdoc

基本配置

首先创建一个配置文件，指定API文档的基本信息和需要扫描的文件：

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

const options = {
  definition: {
    openapi: '3.0.0',  // 使用的OpenAPI版本
    info: {
      title: '我的API文档',  // 文档标题
      version: '1.0.0',     // API版本
    },
  },
  apis: ['./routes/*.js'], // 包含API注释的文件路径
};

const openapiSpec = swaggerJsdoc(options);

编写API注释

在路由文件中添加JSDoc注释：

/**
 * @openapi
 * /users:
 *   get:
 *     summary: 获取用户列表
 *     description: 返回系统中所有注册用户的列表
 *     responses:
 *       200:
 *         description: 成功返回用户列表
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */
app.get('/users', (req, res) => {
  // 业务逻辑实现
});

高级特性

文档验证

在开发过程中，可以启用严格模式，当注释不符合规范时会抛出错误：

const options = {
  failOnErrors: true, // 开启严格验证模式
  // 其他配置...
};

组件复用

使用$ref引用可复用的组件定义：

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

然后在API注释中引用：

/**
 * @openapi
 * /users/{id}:
 *   get:
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: 返回单个用户详情
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 */