OpenAPI文档使用$ref引用TS模型仅返回string问题求助

• 第一，$ref引用不符合OpenAPI规范：OpenAPI的$ref默认指向的是OpenAPI标准Schema对象，不是直接指向TypeScript接口或Mongoose Schema文件，直接填写TS文件相对路径时，文档生成工具无法解析非OpenAPI标准的结构，就会默认 fallback 为string类型。
• 第二，YAML结构缩进错误：你提供的接口注释中application/json和content平级，不符合层级要求，导致整体响应结构解析异常，也是Schema生成错误的诱因之一。
• 第三，缺少类型转换逻辑：你导出的Permission是TS接口、PermissionSchema是Mongoose实例，这两类结构都不能被OpenAPI文档生成工具直接识别为标准Schema定义，需要额外的转换或声明。

步骤1：修正YAML缩进错误 #

先调整接口注释的层级，把$ref指向OpenAPI内置组件的Schema定义，示例如下：

/**
 * @openapi
 * /api/v2/auth/permissions:
 *   get:
 *     description: Get permissions
 *     responses:
 *       200:
 *         description: Get permissions.
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Permission'
 */

步骤2：补充Permission的OpenAPI Schema定义 #

可以根据你的技术栈二选一：

方案A：手动注释声明 #

直接在permission.model.ts中添加OpenAPI组件声明注释：

/**
 * @openapi
 * components:
 *   schemas:
 *     Permission:
 *       type: object
 *       properties:
 *         _id:
 *           type: string
 *           format: objectid
 *         roleId:
 *           type: string
 *         userId:
 *           type: number
 *         groupId:
 *           type: number
 *         createdOn:
 *           type: string
 *           format: date-time
 *         updatedOn:
 *           type: string
 *           format: date-time
 */

方案B：用工具自动生成Schema #

如果不想手写重复定义，可以用对应工具转换现有结构：

• 基于Mongoose Schema生成：使用mongoose-to-swagger库把PermissionSchema转换为标准OpenAPI Schema，在swagger配置的components.schemas字段中引入即可，示例：

const m2s = require('mongoose-to-swagger');
const { PermissionSchema } = require('./model/permission.model');
const swaggerConfig = {
  definition: {
    openapi: '3.0.0',
    components: {
      schemas: {
        Permission: m2s(PermissionSchema)
      }
    }
  },
  apis: ['./routes/*.js']
}

• 基于TS接口生成：如果是NestJS、tsoa等TS技术栈，可以开启框架自带的类型扫描插件，自动把TS interface转换为OpenAPI Schema，不需要额外手写注释。

步骤3：验证生效 #

重新启动服务生成OpenAPI文档，此时200响应的Schema就会正常展示所有字段，不会再返回string类型。

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