为什么 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": {}
  }
]

swagger 示例值的预期结果：

[
  {
    "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 中的确切参数替换类型时，它以 swagger 正确显示它。
我根据接口对 dto 进行了交叉检查，我在 'isOnline' 中添加了错误的字段，它找到并标记了它，这是不好的。
架构以 swagger 方式显示，但也仅在顶层显示，而不是键入的部分。所以它不仅仅是示例值。
已检查堆栈溢出；找到两个相关的线程，但都没有解决它。有人建议手动创建 sub-dtos 而不是类型。嗯...我最好不要那样做。

我做错了什么，或者在文档中遗漏了什么。或者在生成 json.

时，那个 swagger 模块的解析器可能无法提取 type/interface

Answer 1

我错过了 NestJS Documentation: Generics and interfaces 中的一个位置：

Since TypeScript does not store metadata about generics or interfaces, when you use them in your DTOs, SwaggerModule may not be able to properly generate model definitions at runtime.

嗯，很有道理。

In some specific scenarios (e.g. deeply nested arrays, matrices), you may want to describe your type by hand.

所以，适合我的最终设置如下

创建没有类型的 DTO，但匹配 type/interface 结构，就像原始问题中的 'expected result'
request/response 应该用dto打字，例如Result<SomeDto>
当您在该函数中处理数据时，使用 interface/type 键入它，而不是 dto 并且您有交叉检查。

像这个数据是有效的，正确生成了swagger。如需额外的 swagger 信息，请直接在 DTO 中使用装饰器。

Answer 2

您可以使用 OpenAPI CLI plugin.

在 Swagger 中自动显示类型

添加：

  "compilerOptions": {
    "plugins": ["@nestjs/swagger"]
  }

到nest-cli.json，并添加：

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

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

Answer 3

根据文档来自 types and parameters 你只需要使用

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

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

{
"collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": ["@nestjs/swagger/plugin"]
  }
}

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

请注意，如果这不会自动显示它们或显示架构为空，那么您至少要用 @ApiProperty() 修饰 dto 的一个条目，然后刷新页面。这会把事情做好。

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

Why are types in dto not visible in swagger?

javascript

nestjs

nestjs-swagger