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`. ```typescript // ❌ 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. ```typescript // ❌ 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`. ```typescript // ❌ 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: ```typescript @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`: ```typescript // 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: ```typescript @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: ```typescript // 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. ---