【Node.js】自动生成 API 文档

目录

1、直接使用swagger-ui-express

2、配合swagger-jsdoc


如何在Node.js项目中使用 Swagger 来自动生成 API接口文档,使用生成方式有很多种。本文基于swagger-jsdoc+swagger-ui-express快速实现

1、直接使用swagger-ui-express

java 复制代码
// 方便来浏览和测试api
npm i swagger-ui-express
复制代码
java 复制代码
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接口文档,其本质是通过读取该接口对应的注释,然后再转成对应的配置。

2、配合swagger-jsdoc

  • JSDoc 注释是一种特殊的注释语法,用于为 JavaScript 代码添加文档化和类型提示信息。它是基于 JSDoc 规范的一部分,旨在提供一种标准的方式来描述代码的结构、功能和类型信息

  • 作用:接口文档注释有更新,对应的api文档会同步更新。确保接口变更,配置会同时去更改

java 复制代码
npm i swagger-jsdoc
复制代码
java 复制代码
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 };
复制代码
java 复制代码
//在对应的接口,注释对应的文档
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);
相关推荐
databook25 分钟前
处理一批 PDF,怎么算真的处理完了
后端·python
zhensherlock1 小时前
Protocol Launcher 系列:CodeHub 移动端 GitHub 协作利器
前端·javascript·typescript·node.js·自动化·github·js
苏三说技术1 小时前
为什么越来越多人用 Docling ? - 苏三说技术
后端
nice_lcj5201 小时前
【从零理解计算机网络 · 12】登录态的载体:Cookie、Session、Token 在网络层怎么走
后端·计算机网络·面试·jwt·token·cookie·session
jaysee-sjc2 小时前
【黑马点评】Day02:优惠券秒杀与分布式锁
java·分布式·nginx·spring·node.js·tomcat·maven
秋天的怀念_David2 小时前
算法一千零一夜 · 第三十五夜 · 恢复风暴
java·程序人生·算法
考虑考虑3 小时前
JDK27中的加密对象的 PEM 编码
java·后端·java ee
Coder_shen3 小时前
汇川 EVO 系列 PLC EtherNet/IP(CIP)协议通信驱动的 C# 实现
后端
行百里er3 小时前
【Spring Insight 技术分享】如何让 AI 解释失败也不拖垮控制台
后端·spring cloud·开源
行者-全栈开发3 小时前
SpringBoot + GraalVM 原生编译实战:启动时间从8秒到0.5秒的极致优化
java·spring boot·后端