为什么 dto 中的类型在 swagger 中不可见？

Question

我正在根据此文档在我的小型 Nest.js 应用程序中设置 swagger 文档：https ://docs.nestjs.com/recipes/swagger如何设置 dto 以在 swagger 中正确显示架构？更具体地说，嵌套类型。它仅显示顶级键。如果其中一个键是某种类型的，它会将其显示为空对象。这就是我的意思：dto：export class HealthCheckDataDto {    serverStatus: {} // dont have it typed yet;    dbStatus: MongoConnectionStateT;} 昂首阔步：[  {    "serverStatus": {},    "dbStatus": {}  }]招摇示例值的预期结果：[  {    "serverStatus": {},    "dbStatus": {      "isOnline": true,      "msg": "string"    }  }]这是功能：@ApiResponse({ status: 200, description: 'blabla', type: [HealthCheckDataDto] })@ApiResponse({ status: 500, description: 'blabla, but bad', type: [HealthCheckDataDto] })@Get('/api/healthcheck')healthCheckApp(@Res() res: Response<HealthCheckDataDto>) {    // check HCs and setup status code    const healthCheck: HealthCheckI = this.healthcheckService.getFullHealthCheck();    const statusCode = (healthCheck.dbStatus.isOnline) ? HttpStatus.OK : HttpStatus.INTERNAL_SERVER_ERROR;    // return that response    res.status(statusCode).json(healthCheck);}我尝试了什么：当我将类型替换为 dto 中的确切参数时，它会以大摇大摆的方式正确显示它。我对接口进行了 dto 的交叉检查，我在“isOnline”中添加了错误的字段，它找到并标记它，它不好。架构以大摇大摆的方式显示，但也仅显示顶级，而不是键入的部分。所以它不仅仅是示例值。检查堆栈溢出；找到了两个相关的线程，但没有一个解决它。一位建议手动创建子 dto 而不是类型。嗯...我最好不要那样做。我做错了什么，或者错过了文档中的某些内容。或者，该 swagger 模块的解析器在生成 json 时可能无法提取类型/接口。

Answer 1

我错过了NestJS 文档中的一个位置：泛型和接口：

由于 TypeScript 不存储有关泛型或接口的元数据，因此当您在 DTO 中使用它们时，SwaggerModule 可能无法在运行时正确生成模型定义。

嗯，这是有道理的。

在某些特定场景中（例如深度嵌套的数组、矩阵），您可能希望手动描述您的类型。

因此，对我有用的最终设置如下

• 创建没有类型的 DTO，但匹配类型/接口结构，就像原始问题中的“预期结果”一样

• 请求/响应应使用 dto 键入，例如Result<SomeDto>

• 当您在该函数中处理数据时，请使用 interface/type 键入它，而不是 dto 并进行交叉检查。

像这个数据是有效的，swagger 是正确生成的。有关其他招摇信息，请直接在 DTO 中使用装饰器。

Answer 2

您可以使用OpenAPI CLI 插件在 Swagger 中自动显示类型。

添加：

  "compilerOptions": {

    "plugins": ["@nestjs/swagger"]

  }

，nest-cli.json并添加：

import { ApiProperty, ApiBody } from '@nestjs/swagger';

到您的每个 DTO，插件将自动注释和记录您的模式！

Answer 3

根据 类型和参数的文档， 您只需要使用

@Body(), @Query(), @Param()

然后 swagger 模块将自动为您填充内容。这还要求您将nest-cli.json文件更新为

{

"collection": "@nestjs/schematics",

  "sourceRoot": "src",

  "compilerOptions": {

    "plugins": ["@nestjs/swagger/plugin"]

  }

}

那么所有的事情都应该为你完成并生成。

只是提醒一下，如果这没有自动显示它们或显示架构为空，那么您至少装饰 dto 的一个条目，@ApiProperty()然后刷新页面。这将完成任务。