将 Mongoose (TS) 模式 转换为 JSON!

输入 Mongoose (TS) 模式,即可生成示例 JSON!支持 Mongoose, NestJS @Prop。适用于 API 文档和测试请求体(sample JSON)。
Mongoose (TS)
结果
 

将 Mongoose (TS) 模式 转换为 JSON!

给它用 NestJS 的 @nestjs/mongoose 编写的 @Schema() 类,或者普通的 TypeScript 接口,它就会生成一份示例文档,内容与 toJSON() 导出的一致。即使类中没有声明,_id、__v 和时间戳字段也会按 Mongoose 自身的规则添加。

可以用它确定 NestJS 服务中的响应 DTO,或者与团队约定集合中的测试文档应该长什么样。与 JS 页面不同,这里的值取自 TypeScript 的属性类型,而不是 @Prop() 的选项。

使用方法

  1. 把 schema 类文件粘贴到 Mongoose (TS) 框中,作为子文档使用的类也一并放进来,这样数组和嵌套对象才能被填充。
  2. 没有被其他类引用的类会成为根;请确认输出中的是你的主文档类。
  3. 修改 @Schema({ timestamps: true, versionKey: false }) 等选项,观察结果中 createdAt 和 __v 的变化。

示例

输入 (NestJS · @nestjs/mongoose)
@Schema({ _id: false })
export class Attachment {
  @Prop() url: string;
  @Prop() size: number;
}

@Schema({ timestamps: true, versionKey: false })
export class Message {
  @Prop({ type: Types.ObjectId, ref: "Room", required: true })
  roomId: Types.ObjectId;

  @Prop({ required: true })
  text: string;

  @Prop({ type: [Attachment], default: [] })
  attachments: Attachment[];

  @Prop()
  readAt?: Date;
}

export const MessageSchema = SchemaFactory.createForClass(Message);
输出 (JSON)
{
  "_id": "507f1f77bcf86cd799439011",
  "roomId": "507f1f77bcf86cd799439011",
  "text": "",
  "attachments": [
    {
      "url": "",
      "size": 0
    }
  ],
  "readAt": "1970-01-01T00:00:00.000Z",
  "createdAt": "1970-01-01T00:00:00.000Z",
  "updatedAt": "1970-01-01T00:00:00.000Z"
}

Message 引用了 Attachment,所以 Message 是根。开头加上了 _id,timestamps: true 添加了两个日期字段,versionKey: false 去掉了 __v。类型为 Types.ObjectId 的 roomId 变成了一个示例 ObjectId 字符串。

支持的功能

  • 根文档会得到 _id(示例 ObjectId 507f1f77bcf86cd799439011),除非设置 versionKey: false,否则还有 __v: 0;versionKey 为字符串时会改用该名称。
  • @Schema({ timestamps: true }) 会以 ISO 字符串追加 createdAt 和 updatedAt。
  • Types.ObjectId 和 MongooseSchema.Types.ObjectId 变成 ObjectId 字符串;Types.Decimal128 等数值类型变成 0。
  • 其他类的数组,如 Attachment[],变成用该类填充的单元素数组。
  • 选择根时会忽略 type UserDocument = HydratedDocument<User> 这样的类型别名,因此真正的 schema 类会胜出。
  • 不带 @Schema 的普通 interface 声明同样可用,所以 IUser 这样的模型接口可以直接粘贴。

使用场景

NestJS 响应与 Swagger

当服务直接返回 this.model.find().lean() 时,这里能显示客户端实际收到的 key,包括泄漏到响应中的 _id 和 __v。

mongosh 用的测试文档

稍加修改输出,再交给 db.messages.insertOne(),就能快速给本地数据库灌入数据。这时记得把 ObjectId 字符串包成 ObjectId("...")。

注意事项与限制

  • 带 @Schema() 装饰器的嵌套类被视为子文档:它们会有自己的 _id(除非 @Schema({ _id: false }))和时间戳,但不会有 __v。不带 @Schema 的嵌套类仍是普通对象。
  • 字面量形式的 @Prop({ default: ... }) 会用作示例值;required 和 enum 选项不会被读取。对于固定取值集合,请声明 TypeScript 字面量联合类型,会使用其中的第一个值。
  • 用 @Prop({ type: Object }) 声明的 Record<string, any> 会显示为 {"key": null}。
  • 不应用 virtual、toJSON 转换和 select: false。

常见问题

我的 API 会把 _id 改名为 id,但输出显示的是 _id。

输出遵循 Mongoose 默认的 toJSON()。如果 schema 通过 toJSON: { virtuals: true } 或 transform 添加了 id,请在结果中修改 key。

如果类型只写在选项里,比如 @Prop({ type: [String] }) 呢?

值取自属性声明的类型。写成 tags: string[] 会得到 [""];完全没有 TypeScript 类型时,值未知,会变成 null。

能在这里转换 JavaScript 的 new Schema({...}) 吗?

JavaScript 的 schema 对象请使用 Mongoose (JS) 转 JSON 页面,它会直接读取 { type: String, enum: [...] } 这样的 schema 选项。