@nestjs/swagger 用法

自動為 dto 生成 @ApiProperty ()#

在 nest-cli.json 檔案中新增 compilerOptions.plugins：

// https://docs.nestjs.com/openapi/cli-plugin
{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "assets": [
      "assets/**/*"
    ],
    "plugins": [
      {
        "name": "@nestjs/swagger",
        "options": {
          "classValidatorShim": true,
          "introspectComments": true
        }
      }
    ]
  }
}

枚舉屬性#

// 這樣會渲染出一個單選下拉菜單，多選設置 isArray: true
@ApiProperty({
  enum: enumUtils.toObject(AppKind),
  enumName: 'AppKind',
  description: JSON.stringify(enumUtils.toObject(AppKind)),
})
kind: AppKind;

文件上傳#

  // controller 
  @ApiConsumes('multipart/form-data')
  @ApiBody({ type: AppReleaseBodyDto })
  @ApiBearerAuth()
  // 上傳文件和數據在一個請求中：https://stackoverflow.com/a/61165115/7712266
  @UseInterceptors(FilesInterceptor('files'))
  @HttpCode(HttpStatus.OK)
  @Post('release')
  release(
    @UploadedFiles()
    files: Express.Multer.File[],
    @Body() body: AppReleaseBodyDto,
  ) {
    return this.appService.release(files, body);
  }

// AppReleaseBodyDto  
export class AppReleaseBodyDto {
  // 這個僅僅是為了生成 sawgger 文檔而增加的屬性，實際上這個屬性是由 controller 中的 params 接收的
  // 單文件
  // @Allow()
  // @ApiProperty({ type: 'string', format: 'binary' })
  // file: any;
  
  // 多文件
  @Allow()
  @ApiProperty({ type: 'array', items: { type: 'string', format: 'binary' } })
  files: any[];
}

多類型字段#

@ApiExtraModels(
  DeviceBodyBedCallerValueDto,
  DeviceBodyDoorLightValueDto,
  DeviceBodyIntercomExtensionValueDto,
  DeviceBodyLatticeAisleDisplayValueDto,
  DeviceBodyMedicalGasDetectorValueDto,
  DeviceBodyToiletCallerValueDto,
)
export class DeviceCreateBodyDto {
// https://github.com/nestjs/swagger/issues/852#issuecomment-1034934426
// https://docs.nestjs.com/openapi/types-and-parameters#oneof-anyof-allof
@ApiProperty({
    oneOf: [
      { $ref: getSchemaPath(DeviceBodyBedCallerValueDto) },
      { $ref: getSchemaPath(DeviceBodyDoorLightValueDto) },
      { $ref: getSchemaPath(DeviceBodyIntercomExtensionValueDto) },
      { $ref: getSchemaPath(DeviceBodyLatticeAisleDisplayValueDto) },
      { $ref: getSchemaPath(DeviceBodyMedicalGasDetectorValueDto) },
      { $ref: getSchemaPath(DeviceBodyToiletCallerValueDto) },
    ],
  })
  @ValidateNested()
  @Type(() => DeviceBodyValueDto, {
    keepDiscriminatorProperty: true,
    discriminator: {
      property: 'kind',
      subTypes: [
        {
          name: DeviceKind.床位呼叫器.toString(),
          value: DeviceBodyBedCallerValueDto,
        },
        {
          name: DeviceKind.門燈.toString(),
          value: DeviceBodyDoorLightValueDto,
        },
        {
          name: DeviceKind.對講分機.toString(),
          value: DeviceBodyIntercomExtensionValueDto,
        },
        {
          name: DeviceKind.過道顯示器.toString(),
          value: DeviceBodyLatticeAisleDisplayValueDto,
        },
        {
          name: DeviceKind.醫氣檢測儀.toString(),
          value: DeviceBodyMedicalGasDetectorValueDto,
        },
        {
          name: DeviceKind.衛生間呼叫器.toString(),
          value: DeviceBodyToiletCallerValueDto,
        },
      ],
    },
  })
  @IsNotEmptyObject()
  value: DeviceBodyTValueDto;
}

其他#

如果某個 controller.action 上加了 @ApiBody ({type: AppReleaseBodyDto}) ，那麼 dto 文件中每個屬性都需要手動寫 @ApiProperty () 修飾符，因為這個加上了之後，nest-cli.json 配置的自動生成，就會忽略這個 action.
nest-cli.json 中配置的自動為屬性生成修飾符，很坑，特別是在使用 mapped-types 繼承之後，很多需要手動加
對於數組類型的字段也無法自動生成