Files
wiki-server/kiota-compatibility-guidelines.md
dahyeon 815d44c161 Enhances Swagger API documentation and response consistency
Adds comprehensive Swagger decorators across App, Account, and Image controllers to improve API endpoint clarity and detail. This includes adding API tags, operation summaries, response types, authentication requirements, and specific schema for file uploads.

Standardizes error responses within the Page module by introducing a consistent `ErrorResponseDto` for bad requests, not found errors, and unauthorized access. Also refactors the `getPage` endpoint to return a `PageListResponseDto`, ensuring uniform list responses.

Updates DTO definitions in `page.service.ts` with explicit types and nullability for improved accuracy in generated documentation.
2025-11-11 17:14:14 +00:00

5.2 KiB
Raw Permalink Blame History

Here’s a concise English version of the essential Kiota-compatibility guidelines, suitable for giving to another AI agent or automated generator:


🧩 Kiota Compatibility Guidelines for NestJS Swagger APIs

Goal: Ensure the OpenAPI spec generated by NestJS Swagger can be fully parsed by Kiota without losing endpoints or models.


✅ 1. OpenAPI Version

  • Use OpenAPI 3.0.x (Kiota doesn’t support 3.1).
  • Avoid non-standard or experimental extensions.

✅ 2. Request & Response Schemas

  • Always define a schema for every request and 2XX response.
  • Use application/json as the single content type.
  • Avoid multiple response formats per endpoint.
  • Empty 204 responses → no type, only description.
  • CRITICAL: Always explicitly specify type in @ApiProperty for all DTO fields, especially when using nullable: true or format.
    // ❌ BAD - Kiota warns about format on nullable types
    @ApiProperty({ format: 'uuid', nullable: true })
    id?: string;
    
    // ✅ GOOD - Explicitly specify type
    @ApiProperty({ type: String, format: 'uuid', nullable: true })
    id?: string;
    

✅ 3. Error Handling

  • Define object-type error schemas for 4XX/5XX responses.
  • Avoid array-type root errors ([{message}] → { errors: [...] }).
  • Kiota maps errors to typed exceptions only if schema exists.
  • CRITICAL: Every endpoint must have @ApiResponse decorators, even if it just returns a simple string.
    // ❌ BAD - No Swagger decorators
    @Get()
    healthCheck(): string {
      return 'OK';
    }
    
    // ✅ GOOD - Has response decorator
    @Get()
    @ApiOperation({ summary: 'Health check' })
    @ApiResponse({ status: 200, description: 'Server is healthy', type: String })
    healthCheck(): string {
      return 'OK';
    }
    

✅ 4. Models & Polymorphism

  • Use allOf + discriminator for inheritance.
  • Avoid oneOf/anyOf unless you add a discriminator and reference named components.
  • Never use anonymous inline schemas or type: any.
  • CRITICAL: For endpoints that can return different response shapes, create a wrapper DTO instead of using oneOf.
    // ❌ BAD - oneOf without discriminator
    @ApiResponse({ 
      schema: {
        oneOf: [
          { $ref: '#/components/schemas/PageDto' },
          { type: 'array', items: { $ref: '#/components/schemas/PageDto' } }
        ]
      }
    })
    
    // ✅ GOOD - Consistent wrapper type
    export class PageListResponseDto {
      @ApiProperty({ type: [PageDto] })
      pages: PageDto[];
    }
    
    @ApiResponse({ type: PageListResponseDto })
    

✅ 5. Query & Header Parameters

  • Define query params individually (@ApiQuery per field).
  • Avoid deepObject style; use simple form style.
  • Enums in queries become strings in Kiota.
  • Kiota does not auto-generate custom header fields — document required headers.

✅ 6. Authentication

  • Use standard Bearer, OAuth2, or openIdConnect security schemes.
  • Include openIdConnectUrl or token endpoint if applicable.
  • Apply @ApiBearerAuth() on secured endpoints.

✅ 7. File Uploads

  • Prefer JSON metadata + binary file upload separately.
  • If multipart is required, use Kiota form-serialization packages (@microsoft/kiota-serialization-form).
  • Always use @ApiConsumes('multipart/form-data') and define proper @ApiBody schema:
    @Post()
    @ApiConsumes('multipart/form-data')
    @ApiBody({
      schema: {
        type: 'object',
        properties: {
          file: { type: 'string', format: 'binary' }
        }
      }
    })
    @ApiResponse({ status: 201, type: UploadResultDto })
    uploadFile(@UploadedFile() file: Express.Multer.File) {
      // ...
    }
    

✅ 8. Validation & Generation

  • Check for Kiota CLI warnings (kiota generate --log-level info).
  • Verify all endpoints produce request builders.
  • Re-generate after Swagger or Kiota updates.

🔧 Common Kiota Warnings & Solutions

Warning: "The format X is not supported by Kiota for the type Object"

Cause: Using format (uuid, date-time) on nullable types without explicitly specifying type.

Solution: Always add type: String (or appropriate type) to @ApiProperty:

// Before
@ApiProperty({ format: 'uuid', nullable: true })
parentId?: string;

// After
@ApiProperty({ type: String, format: 'uuid', nullable: true })
parentId?: string;

Warning: "Could not create error type for 4XX/5XX in [EndpointName]"

Cause: Missing Swagger decorators on endpoints.

Solution: Add @ApiOperation, @ApiResponse, and @ApiTags to all endpoints:

@ApiTags('MyController')
@Controller('my-route')
export class MyController {
  @Get()
  @ApiOperation({ summary: 'Get data' })
  @ApiResponse({ status: 200, type: MyDto })
  getData() { /* ... */ }
}

Warning: "oneOf/anyOf without discriminator"

Cause: Using oneOf in response schemas without a discriminator field.

Solution: Create a wrapper DTO with a consistent structure:

// Instead of returning PageDto | PageDto[]
// Always return PageListDto { pages: PageDto[] }

Outcome: Following these rules ensures every NestJS API route and model is fully generated by Kiota's TypeScript client without loss of fidelity.