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.