型推論

3つの自動化メカニズムです。インターフェースはインラインスキーマに、class-validatorはJSON Schemaに、@HttpCode()は正しいステータスになります。

インターフェース型のDTO

レスポンスまたはボディの型がTypeScriptのinterface(クラスではない)の場合、インターフェースは実行時に消去されるため、Swaggerはそれをtype:の値として使えません。nestjs-docfyはこれを自動的に検出し、コードを一切変更することなくインラインのschema:オブジェクトを生成します。

Sua interface
// Your existing interface (no need to convert to a class)
export interface RegisterResponseDto {
  success: boolean;
  message: string | null;
}

生成される出力:

Generated
ApiResponse({
  status: 201,
  description: 'Created',
  schema: {
    type: 'object',
    properties: {
      success: { type: 'boolean' },
      message: { type: 'string', nullable: true },
    },
    required: ['success'],
  },
}),

対応範囲: プリミティブ、null許容ユニオン(T | null)、配列、ネストされたインターフェース、そしてオプショナルなプロパティ(requiredから除外されます)です。

class-validatorによる推論

DTOクラスがclass-validatorデコレーターを使っており、そのプロパティにまだ@ApiPropertyが付いていない場合、nestjs-docfyはバリデーションデコレーターから完全なJSON Schemaを推論します。手動での注釈は不要です。

create-user.dto.ts
// create-user.dto.ts
import { IsString, IsEmail, MinLength, IsOptional } from 'class-validator';

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  name: string;

  @IsEmail()
  email: string;

  @IsOptional()
  @IsString()
  bio?: string;
}

生成される出力:

ts
ApiBody({
  schema: {
    type: 'object',
    properties: {
      name:  { type: 'string', minLength: 2 },
      email: { type: 'string', format: 'email' },
      bio:   { type: 'string' },
    },
    required: ['name', 'email'],
  },
}),

対応デコレーター

Decorator
@IsString
@IsEmail
@IsUrl
@IsUUID
@IsDateString
@IsNumber
@IsInt
@IsBoolean
@IsArray
@Min
@Max
@MinLength
@MaxLength
@IsOptional
既存の注釈を保持する

クラスのいずれかのプロパティにすでに@ApiPropertyが付いている場合、推論はスキップされtype: ClassNameが代わりに使われます。既存のSwagger注釈が上書きされることはありません。

@HttpCode()への対応

NestJSの@HttpCode()デコレーターは、ルートハンドラーのデフォルトHTTPステータスコードを上書きします。nestjs-docfyはこれを自動的に読み取り、生成されるApiResponseで正しいコードを使用します。

users.controller.ts
// users.controller.ts
@Post('logout')
@HttpCode(204)
logout(): void { ... }

生成される出力:

ts
logout: [
  ApiOperation({ summary: 'Logout' }),
  ApiResponse({ status: 204, description: 'No Content' }),
],

@HttpCode()がない場合はデフォルトのコードが適用されます。@Postは201、それ以外のHTTP動詞は200です。