10

我正在根据此文档在我的小型 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 时可能无法提取类型/接口。

4

3 回答 3

8

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

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

嗯，这是有道理的。

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

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

  • 创建没有类型的 DTO，但匹配类型/接口结构，就像原始问题中的“预期结果”一样
  • 请求/响应应使用 dto 输入，例如Result<SomeDto>
  • 当您在该函数中处理数据时，请使用 interface/type 键入它，而不是 dto 并进行交叉检查。

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

于 2020-04-01T07:52:20.870 回答
2

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

添加：

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

，nest-cli.json并添加：

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

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

于 2021-10-06T13:12:59.563 回答
1

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

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

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

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

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

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

于 2022-01-02T03:09:23.647 回答