@nestjs/swagger の使用方法

自動的に @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 を使用した後は手動で追加する必要があります。
配列型のフィールドについても自動的に生成されません。