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

2.2 KiB
Raw 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.

✅ 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.