无需基于类控制器的TypeScript Express项目Swagger UI适配问题咨询

完全可以不用迁移到基于类的开发模式，就能实现现有项目中TypeScript类型和Swagger的自动联动，不需要重构现有业务代码，以下是可直接落地的实现方案：

方案1：swagger-jsdoc 配合现有TS类型（改动最小） #

这是最适配存量项目的方案，不需要改现有路由逻辑，只需要新增少量注释和配置即可：

• 安装依赖：

  npm install swagger-jsdoc swagger-ui-express
  # TS项目额外安装类型
  npm install @types/swagger-jsdoc @types/swagger-ui-express -D
  

• 直接复用你已经定义的TS类型作为Swagger的Schema，在函数式路由上方加对应Swagger注释即可，示例如下：

  import { Request, Response } from 'express'
  
  // 你项目中已有的类型定义，无需修改
  type CreateUserReq = {
    username: string
    age: number
    email: string
  }
  
  type CreateUserRes = {
    id: string
    username: string
  }
  
  /**
   * @swagger
   * /users:
   *   post:
   *     summary: 创建新用户
   *     requestBody:
   *       required: true
   *       content:
   *         application/json:
   *           schema:
   *             $ref: '#/components/schemas/CreateUserReq'
   *     responses:
   *       200:
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/CreateUserRes'
   */
  const createUser = async (req: Request<{}, {}, CreateUserReq>, res: Response<CreateUserRes>) => {
    // 现有业务逻辑保持不变
    const user = await userService.create(req.body)
    res.json(user)
  }
  

• 配置swagger-jsdoc时将类型定义文件的路径加入扫描范围，工具会自动提取TS类型生成Swagger的components schema，无需手动重复编写结构。

方案2：tsoa 自动扫描类型生成（几乎零额外配置） #

tsoa 虽然常被用于类装饰器模式，但完全支持函数式路由的扫描，只需要在tsoa.json配置中指定路由文件和类型根路径，它会自动读取所有函数式路由的Request、Response泛型类型，自动生成完整的Swagger JSON，连注释都可以少写大部分。

方案3：自定义TS类型转换脚本（灵活度最高） #

如果不想引入额外的重量级依赖，可以直接调用TypeScript编译器API提取你项目中定义的接口、类型结构，批量转换为Swagger Schema，和你手动维护的路径配置合并即可，100%适配你现有项目的代码结构，不需要做任何业务逻辑调整。

所有方案都不需要将现有函数式路由改造为类，只需要复用已经写好的TS类型即可完成Swagger联动。

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