Usage of @nestjs/swagger

Automatically generate @ApiProperty() for dto#

Add compilerOptions.plugins in the nest-cli.json file:

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

Enum properties#

// This will render a radio dropdown menu, set isArray: true for multiple selection
@ApiProperty({
  enum: enumUtils.toObject(AppKind),
  enumName: 'AppKind',
  description: JSON.stringify(enumUtils.toObject(AppKind)),
})
kind: AppKind;

File upload#

  // controller 
  @ApiConsumes('multipart/form-data')
  @ApiBody({ type: AppReleaseBodyDto })
  @ApiBearerAuth()
  // upload a file and data in a request：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 {
  // This is only added to generate sawgger documentation, and this property is actually received by the params in the controller
  // Single file
  // @Allow()
  // @ApiProperty({ type: 'string', format: 'binary' })
  // file: any;
  
  // Multiple files
  @Allow()
  @ApiProperty({ type: 'array', items: { type: 'string', format: 'binary' } })
  files: any[];
}

Multiple type fields#

@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;
}

Others#

If @ApiBody({ type: AppReleaseBodyDto }) is added to a controller.action, each property in the dto file needs to be manually annotated with @ApiProperty(), because after adding this, the automatic generation configured in nest-cli.json will ignore this action.
The automatic generation of decorators configured in nest-cli.json is very tricky, especially when using mapped-types inheritance, many need to be manually added.
It is also unable to automatically generate for array type fields.