如何用tsoa或其他工具为Express RequestHandler端点生成Swagger文档？

一、适配现有RequestHandler写法的tsoa方案 #

不用完全重构代码，只需用tsoa的类控制器做一层包装，就能让tsoa识别并生成Swagger文档：

1. 抽离验证链与业务逻辑
   先把验证规则和处理函数单独抽离，保留原有写法：

// src/controllers/category-handlers.ts
import { RequestHandler, body } from 'express';
import { CategoryModel } from '../models';

// 验证链
export const createCategoryValidation = [
  body('name').notEmpty().withMessage('分类名称不能为空'),
  body('parentId').optional().isMongoId().withMessage('父分类ID格式错误')
];

// 业务逻辑处理函数
export const createCategoryHandler: RequestHandler = async (req, res, next) => {
  try {
    const newCategory = await CategoryModel.create(req.body);
    res.status(201).json(newCategory);
  } catch (err) {
    next(err);
  }
};

2. 用tsoa类控制器包装
   创建tsoa兼容的控制器类，通过装饰器声明路由、请求方法、中间件，再在类方法里调用原有handler：

// src/controllers/category-controller.ts
import { Controller, Post, Route, Middlewares, Body, Response } from 'tsoa';
import { Request, Response as ExpressResponse, NextFunction } from 'express';
import { createCategoryValidation, createCategoryHandler } from './category-handlers';

// 定义请求体和响应体类型
interface CreateCategoryReq {
  name: string;
  parentId?: string;
}

interface CategoryRes {
  _id: string;
  name: string;
  parentId?: string;
  createdAt: string;
}

@Route('categories')
export class CategoryController extends Controller {
  @Post()
  @Middlewares(createCategoryValidation) // 挂载验证链
  @Response<CategoryRes>(201, '分类创建成功') // 定义响应体
  public async createCategory(
    @Body() body: CreateCategoryReq, // 定义请求体类型
    req: Request,
    res: ExpressResponse,
    next: NextFunction
  ): Promise<void> {
    req.body = body; // 确保类型对齐
    await createCategoryHandler(req, res, next);
  }
}

3. 生成文档
   按照tsoa常规流程配置（更新tsconfig、tsoa.json），执行生成命令后，tsoa会根据类上的装饰器生成完整Swagger文档，原有业务逻辑和验证链完全保留。

二、替代工具推荐 #

如果不想用tsoa的类写法，以下工具更适配Express的RequestHandler风格：

1. swagger-jsdoc + swagger-ui-express #

通过JSDoc注释直接在RequestHandler上标记API信息，自动生成Swagger文档，完全不需要类结构：

• 安装依赖

npm install swagger-jsdoc swagger-ui-express

• 配置Swagger

// src/config/swagger.ts
import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';
import { Express } from 'express';

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '分类管理API',
      version: '1.0.0',
      description: '分类创建、查询等接口文档'
    }
  },
  apis: ['./src/controllers/*.ts', './src/routes/*.ts'] // 指定要扫描的文件路径
};

const swaggerSpec = swaggerJsdoc(swaggerOptions);

export const setupSwagger = (app: Express) => {
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
};

• 在RequestHandler上加注释
  直接在处理函数上方写JSDoc，swagger-jsdoc会自动解析：

// src/controllers/category.ts
import { RequestHandler, body } from 'express';
import { CategoryModel } from '../models';

/**
 * @swagger
 * /categories:
 *   post:
 *     summary: 创建新分类
 *     tags: [分类管理]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [name]
 *             properties:
 *               name:
 *                 type: string
 *                 description: 分类名称
 *               parentId:
 *                 type: string
 *                 description: 父分类ID（可选，需为MongoDB ID格式）
 *     responses:
 *       201:
 *         description: 创建成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 _id:
 *                   type: string
 *                 name:
 *                   type: string
 *                 parentId:
 *                   type: string
 *                 createdAt:
 *                   type: string
 *                   format: date-time
 */
export const createCategoryHandler: RequestHandler = async (req, res, next) => {
  try {
    const newCategory = await CategoryModel.create(req.body);
    res.status(201).json(newCategory);
  } catch (err) {
    next(err);
  }
};

// 验证链
export const createCategoryValidation = [
  body('name').notEmpty().withMessage('分类名称不能为空'),
  body('parentId').optional().isMongoId().withMessage('父分类ID格式错误')
];

• 启动服务
  把handler挂载到Express路由，调用setupSwagger启动文档服务，访问/api-docs即可查看生成的Swagger页面。

2. express-openapi-validator（结合手动OpenAPI规范） #

如果愿意手动编写OpenAPI规范文件（yaml/json），可以用这个工具做请求验证，同时用swagger-ui-express展示文档：

• 编写openapi.yaml定义所有接口的请求、响应规则
• 用express-openapi-validator中间件挂载到Express，自动做请求验证
• 用swagger-ui-express展示规范文件生成的文档
  这种方式适合需要严格遵循OpenAPI规范的场景，业务逻辑依然用RequestHandler实现。

内容的提问来源于stack exchange，提问作者Igor Micev