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