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.
2.2 KiB
2.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.
✅ 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+discriminatorfor inheritance. - Avoid
oneOf/anyOfunless you add adiscriminatorand reference named components. - Never use anonymous inline schemas or
type: any.
✅ 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).
✅ 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.