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

186 lines
5.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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.
---