自動的に @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 {
// これは実際にはコントローラーの params で受け取られる属性であるため、swagger ドキュメントを生成するために追加されました
// 単一ファイル
// @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 の自動生成設定が無視されるためです。
- nest-cli.json で自動的に属性の修飾子を生成する設定は非常に厄介であり、特に mapped-types を使用した後は手動で追加する必要があります。
- 配列型のフィールドについても自動的に生成されません。