Files
wiki/kiota-compatibility-guidelines.md
T
dahyeon 0a718651b2 Updates page API interactions and regenerates Kiota client
Refactors page-related API interactions and client-side logic to align with an updated Kiota client and recent backend API changes.

*   Regenerates Kiota client with `--clear-cache` to ensure integration with the latest OpenAPI specification.
*   Adapts page data mapping to handle Kiota's improved type generation for `content`, `parentPageId`, `createdAt`, `updatedAt`, and `sortOrder`, which now correctly map to primitive types.
*   Updates page listing and detail fetching to consume responses wrapped in `PageListResponseDto` instead of direct arrays.
*   Removes explicit `userId` parameters from `createPage`, `updatePage`, and `deletePage` functions, as user context is now handled by server-side authentication.
*   Extends the `updatePage` functionality to allow modifications of `parentId` and `sortOrder`.
*   Standardizes API error responses across Kiota-generated endpoints to use a generic `ErrorResponseDto`.
*   Corrects Kiota-generated response types for several primitive endpoints from `ArrayBuffer` to `string`.
*   Enhances the UI to support space-aware page creation and navigation flows, including a new "Add Sub Page" option directly from the sidebar for hierarchical page management.
2025-11-11 17:13:58 +00:00

78 lines
2.2 KiB
Markdown
Raw 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`.
---
### ✅ 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.
---
### ✅ 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`.
---
### ✅ 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`).
---
### ✅ 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.
---
**Outcome:** Following these rules ensures every NestJS API route and model is fully generated by Kiota’s TypeScript client without loss of fidelity.
---