本文介绍在 Node.js 项目中利用 swagger-jsdoc 与 swagger-ui-express 自动生成 API 文档的两种方法。对比了手动配置与基于 JSDoc 注释自动更新的实现方式，并提供相关代码示例及参考链接，帮助开发者高效维护接口文档。
在 Node.js 项目中，有多种方式可以利用 Swagger 自动生成 API 接口文档。本文将介绍如何结合
swagger-jsdoc与swagger-ui-express快速实现这一功能。
方案一：直接使用 swagger-ui-express
// 方便来浏览和测试api
npm i swagger-ui-express
import { Express } from 'express';
import swaggerUi from 'swagger-ui-express';
const options = {
openapi: "3.0.3",
info: {
title: '文档相关接口',
version: '1.0.0',
description: 'API documentation using Swagger',
},
tags: [{
name: "develop",
description: "开发者站点管理接口",
}],
paths: {
"/develop": {
"get": {
"tags": ["develop"],
"description": "获取文档列表!",
"responses": {
"200": {
"description":"返回字符串数组"
}
}
}
}
}
}
const swaggerInstall = (app: Express) => {
app.use(
'/apidoc',
swaggerUi.serve,
swaggerUi.setup(options)
);
};
export { swaggerInstall };
若直接通过配置生成接口文档，当接口发生变更时，需要同步修改配置，操作相对繁琐。此时可引入 swagger-jsdoc，通过在接口代码中添加注释信息，实现 API 文档的自动更新。其原理是读取接口对应的注释内容，并将其转换为相应的配置信息。
方案二：配合 swagger-jsdoc 使用
JSDoc 注释是一种特殊的语法，用于为 JavaScript 代码提供文档化和类型提示信息。它基于 JSDoc 规范，旨在以标准方式描述代码的结构、功能及类型信息。
主要作用：当接口文档注释发生更新时，生成的 API 文档会同步更新，确保接口变更与配置保持一致。
npm i swagger-jsdoc
import { Express } from 'express';
import path from 'path';
import swaggerDoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';
const swaggerOptions = {
swaggerDefinition: {
info: {
title: '文档相关接口',
version: '1.0.0',
description: 'API documentation using Swagger',
},
},
apis: [path.join(__dirname, './routes/*.ts')], // 指定包含 API 路由的文件或文件夹路径
};
const swaggerInstall = (app: Express) => {
app.use(
'/apidoc',
swaggerUi.serve,
swaggerUi.setup(swaggerDoc(swaggerOptions))
);
};
export { swaggerInstall };
//在对应的接口，注释对应的文档
import express from 'express';
import {
developGetFile,
developGetFileList,
} from '../controllers/developControllers';
const router = express.Router();
/**
* @openapi
* /develop:
* get:
* tags: [develop]
* description: 获取文档列表!
* responses:
* 200:
* description: 返回字符串数组.
*/
router.get('/', developGetFileList);
参考资料
https://editor.swagger.io/
https://jsdoc.app/
https://github.com/Surnet/swagger-jsdoc
https://github.com/scottie1984/swagger-ui-express
以上即为在 Node.js 中使用 Swagger 自动生成 API 接口文档的详细内容，更多关于 Node.js Swagger 生成 API 文档的资料请关注本站其它相关文章！