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.
5.2 KiB
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/jsonas the single content type. - Avoid multiple response formats per endpoint.
- Empty 204 responses → no
type, onlydescription. - CRITICAL: Always explicitly specify
typein@ApiPropertyfor all DTO fields, especially when usingnullable: trueorformat.// ❌ 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
@ApiResponsedecorators, 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+discriminatorfor inheritance. - Avoid
oneOf/anyOfunless you add adiscriminatorand 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 (
@ApiQueryper field). - Avoid
deepObjectstyle; use simpleformstyle. - Enums in queries become strings in Kiota.
- Kiota does not auto-generate custom header fields — document required headers.
✅ 6. Authentication
- Use standard
Bearer,OAuth2, oropenIdConnectsecurity schemes. - Include
openIdConnectUrlor 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@ApiBodyschema:@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.