Openapi Swagger Codegen Expert

OpenAPI & Swagger Codegen Expert

English | Bahasa Indonesia

English

Description

Dedicated expert guide for API contract-first development using OpenAPI 3.1, Swagger UI, and automated code generation. Covers generating strictly typed API clients (using openapi-typescript, Orval, or Microsoft Kiota), scaffolding server stubs, and implementing contract testing to ensure backend APIs always match their documentation.

Trigger Conditions

• Setting up API documentation (Swagger UI, Redoc, Scalar).
• Generating API client code for frontend/mobile apps.
• Authoring OpenAPI 3.x specifications (openapi.yaml or JSON).
• Implementing contract testing (e.g., using Dredd or Prism).
• Migrating from manual fetch wrappers to auto-generated typed API clients.

Best Practices & Workflow

1. Contract-First Approach: Always write or define the OpenAPI specification before writing any backend code. This serves as the single source of truth for both frontend and backend teams.
2. Strict Type Generation:
   • Use openapi-typescript for generating raw TS definitions.
   • Use Orval for generating React Query (TanStack Query) hooks directly from the OpenAPI spec.
   • Use Microsoft Kiota for multi-language SDK generation.
3. Automated Validation: Integrate API schema validation in the CI/CD pipeline using tools like Spectral to enforce API design standards.
4. Mocking: Use tools like Prism to spin up mock servers from the OpenAPI spec, allowing frontend teams to start development immediately.

Bahasa Indonesia

Integrasi Orkestrasi

Terhubung dan mengorkestrasi skill domain yang relevan seperti brainstorming, zero-to-prod-orchestrator, dan project-context-mapper untuk memastikan eksekusi yang kohesif.

Deskripsi

Panduan ahli khusus untuk pengembangan API dengan pendekatan contract-first menggunakan OpenAPI 3.1, Swagger UI, dan otomatisasi pembuatan kode (codegen). Mencakup pembuatan klien API yang strictly typed (menggunakan openapi-typescript, Orval, atau Microsoft Kiota), scaffolding untuk server, dan implementasi contract testing untuk memastikan backend selalu sesuai dengan dokumentasinya.

Kondisi Pemicu

• Mengatur dokumentasi API (Swagger UI, Redoc, Scalar).
• Men-generate kode klien API untuk aplikasi frontend/mobile.
• Menulis spesifikasi OpenAPI 3.x (openapi.yaml atau JSON).
• Mengimplementasikan contract testing (misalnya menggunakan Dredd atau Prism).
• Migrasi dari wrapper fetch manual ke klien API yang otomatis ter-generate dan typed.

Panduan Implementasi

1. Pendekatan Contract-First: Selalu tulis/definisikan spesifikasi OpenAPI sebelum menulis kode backend. Ini menjadi sumber kebenaran tunggal (single source of truth) untuk tim frontend dan backend.
2. Pembuatan Tipe yang Ketat (Strict Type Generation):
   • Gunakan openapi-typescript untuk menghasilkan definisi TypeScript murni.
   • Gunakan Orval untuk men-generate React Query (TanStack Query) hooks secara otomatis dari spek OpenAPI.
   • Gunakan Microsoft Kiota untuk pembuatan SDK multi-bahasa.
3. Validasi Otomatis: Integrasikan validasi skema API di pipeline CI/CD menggunakan tool seperti Spectral untuk memastikan standar desain API terpenuhi.
4. Mocking: Gunakan tool seperti Prism untuk menjalankan mock server dari spesifikasi OpenAPI, memungkinkan tim frontend memulai pengembangan tanpa harus menunggu backend selesai.

Orchestration & Integration

• Connects to api-design-expert for the core design rules.
• Connects to ci-cd-devops-architect to implement CI/CD validation.
• Connects to senior-frontend / tanstack-query-expert to consume the generated clients.