【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);
相关推荐
一只叫煤球的猫4 小时前
写代码很6,面试秒变菜鸟?不卖课,面试官视角走心探讨
前端·后端·面试
bobz9655 小时前
tcp/ip 中的多路复用
后端
bobz9655 小时前
tls ingress 简单记录
后端
皮皮林5516 小时前
IDEA 源码阅读利器,你居然还不会?
java·intellij idea
你的人类朋友6 小时前
什么是OpenSSL
后端·安全·程序员
bobz9656 小时前
mcp 直接操作浏览器
后端
前端小张同学8 小时前
服务器部署 gitlab 占用空间太大怎么办,优化思路。
后端
databook9 小时前
Manim实现闪光轨迹特效
后端·python·动效
武子康9 小时前
大数据-98 Spark 从 DStream 到 Structured Streaming:Spark 实时计算的演进
大数据·后端·spark
该用户已不存在10 小时前
6个值得收藏的.NET ORM 框架
前端·后端·.net