如何在 NestJs 生成的 Swagger 文档中定义响应主体对象？

Question

我正在使用 NestJs 及其 Swagger 插件自动生成 API 文档。

问题是，我不知道如何使响应模式出现在文档中。在我的 GET 路由中，我得到的只是“Code 200”，没有数据结构。

我有一个典型的设置，其中控制器方法使用相应的服务方法，而服务方法又使用 TypeOrm 存储库。例如：

@Get()
 findAll() {    
   return this.usersService.findAll();
}

我尝试使用@ApiResponse装饰器，但没有真正看到任何方法让它达到这个目的。此外，创建 user.dto.ts 并将其设为控制器路由的返回类型并没有任何好处。

最终，这就是我在 Swagger 中得到的：

我如何定义响应主体架构？

Answer 1

您可以将type和isArray属性与装饰器系列结合使用ApiResponse。例如：

@ApiOkResponse({
    description: 'The user records',
    type: User,
    isArray: true
})
@Get()
 findAll() {    
   return this.usersService.findAll();
}

此外，考虑使用Swagger CLI 插件来帮助您在构建时自动应用这些装饰器，而不必手动保持所有内容同步。

Answer 2

您可以使用以下方式注释控制器操作ApiExtraModels：

import { ApiExtraModels, ApiResponse, getSchemaPath } from '@nestjs/swagger'
import { Controller, Get, Param } from '@nestjs/common';

@Controller('users')
export class UsersController {


 @ApiExtraModels(UserDto)
 @ApiResponse({
    status: 200,
    schema: {
      $ref: getSchemaPath(UserDto),
    },
  })
  @Get('/:userId')
  getById(@Param('userId') userId: string): UserDto {
     ... something happens ... 
     return myUserDto;
  }

}

并且您还必须UserDto使用以下方式注释属性ApiProperty：

import { ApiProperty } from '@nestjs/swagger'
import { Expose } from 'class-transformer'
import { IsString } from 'class-validator'

export class UserDto {

  @ApiProperty()
  @IsString()
  @Expose()
  id: string;
}

顺便说一句，检查用于生成 ApiProperty 的 CLI 插件