为什么 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 中自动显示类型。添加：&nbsp; "compilerOptions": {&nbsp; &nbsp; "plugins": ["@nestjs/swagger"]&nbsp; }，nest-cli.json并添加：import { ApiProperty, ApiBody } from '@nestjs/swagger';到您的每个 DTO，插件将自动注释和记录您的模式！

Answer 3

根据 类型和参数的文档， 您只需要使用@Body(), @Query(), @Param()然后 swagger 模块将自动为您填充内容。这还要求您将nest-cli.json文件更新为{"collection": "@nestjs/schematics",&nbsp; "sourceRoot": "src",&nbsp; "compilerOptions": {&nbsp; &nbsp; "plugins": ["@nestjs/swagger/plugin"]&nbsp; }}那么所有的事情都应该为你完成并生成。只是提醒一下，如果这没有自动显示它们或显示架构为空，那么您至少装饰 dto 的一个条目，@ApiProperty()然后刷新页面。这将完成任务。