OpenAPI & Swagger Codegen Expert (Contract-First 2026)

English | Bahasa Indonesia

---

<a name="english"></a>

English

Description

Dedicated expert guide for API contract-first development using OpenAPI 3.1 (with full JSON Schema 2020-12 alignment), interactive documentation (Scalar, Swagger UI, Redoc), and automated end-to-end client code generation. Covers generating strictly typed SDKs using openapi-typescript and openapi-fetch, creating automatic TanStack Query v5 hooks with Orval, scaffolding multi-language SDKs with Microsoft Kiota, and enforcing API design governance via Spectral in CI/CD pipelines.

Trigger Conditions

• Scaffolding modern RESTful API contracts before writing server code (Phase 1/4).
• Generating type-safe frontend API clients and TanStack Query hooks.
• Configuring interactive API documentation with Scalar or Swagger UI.
• Setting up automated contract testing with Prism or Pact.
• Migrating manual, unvalidated fetch() calls to auto-generated typed clients.

Production OpenAPI 3.1 Specification Example

# specs/openapi.yaml
openapi: 3.1.0
info:
  title: Vibes Core Service API
  version: 1.0.0
  description: High-scale contract-first API with strict schema validation.
servers:
  - url: https://api.vibesplug.internal/v1
    description: Production Cluster
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Place an atomic order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          $ref: '#/components/responses/ValidationError'

components:
  schemas:
    CreateOrderRequest:
      type: object
      required: [customerId, items, totalCents]
      properties:
        customerId:
          type: string
          format: uuid
        items:
          type: array
          items:
            type: object
            required: [productId, quantity]
            properties:
              productId: { type: string }
              quantity: { type: integer, minimum: 1 }
        totalCents:
          type: integer
          minimum: 1
    OrderResponse:
      type: object
      required: [id, status, createdAt]
      properties:
        id: { type: string, format: uuid }
        status: { type: string, enum: [PENDING, PAID, FULFILLED] }
        createdAt: { type: string, format: date-time }

Orval Configuration for TanStack Query v5

// orval.config.ts
import { defineConfig } from 'orval';

export default defineConfig({
  api: {
    input: './specs/openapi.yaml',
    output: {
      mode: 'tags-split',
      target: './src/api/generated/endpoints',
      schemas: './src/api/generated/models',
      client: 'react-query',
      httpClient: 'fetch',
      override: {
        query: {
          useQuery: true,
          useMutation: true,
          signal: true,
        },
        mutator: {
          path: './src/api/custom-fetch-instance.ts',
          name: 'customFetch',
        },
      },
    },
  },
});

Type-Safe Client Invocation (openapi-fetch)

// src/api/client.ts
import createClient from 'openapi-fetch';
import type { paths } from './generated/schema';

export const apiClient = createClient<paths>({ baseUrl: 'https://api.vibesplug.internal/v1' });

// Fully type-checked: parameters, request body, and responses are verified at compile-time
export async function submitOrder(customerId: string, productId: string, quantity: number, totalCents: number) {
  const { data, error } = await apiClient.POST('/orders', {
    body: { customerId, items: [{ productId, quantity }], totalCents }
  });
  if (error) throw new Error(`Order placement failed: ${error}`);
  return data; // Type: OrderResponse
}

Orchestration & Integration

• api-design-expert: Provides REST architectural standards, versioning, and status code rules.
• spec-driven-development-expert: Connects OpenAPI specs with TypeSpec and BDD test suites.
• tanstack-query-expert: Consumes generated React Query hooks on the frontend.
• ci-cd-devops-architect: Runs Spectral linting (spectral lint specs/openapi.yaml) in CI.

---

<a name="bahasa-indonesia"></a>

Bahasa Indonesia

Integrasi Orkestrasi

Terhubung dan mengorkestrasi skill domain yang relevan seperti api-design-expert, spec-driven-development-expert, tanstack-query-expert, dan ci-cd-devops-architect untuk memastikan eksekusi yang kohesif.

Deskripsi

Panduan ahli khusus untuk pengembangan API dengan pendekatan contract-first menggunakan OpenAPI 3.1 (dengan dukungan penuh JSON Schema 2020-12), dokumentasi interaktif modern (Scalar, Swagger UI, Redoc), dan otomatisasi pembuatan klien SDK. Mencakup pembuatan SDK tipe ketat (strictly typed) menggunakan openapi-typescript dan openapi-fetch, pembuatan hooks TanStack Query v5 otomatis via Orval, scaffolding SDK multi-bahasa dengan Microsoft Kiota, serta penegakan standar desain API menggunakan Spectral pada pipeline CI/CD.

Kondisi Pemicu

• Merancang spesifikasi API REST sebelum menulis kode backend (Fase 1/4).
• Menghasilkan klien API frontend dan hooks React Query yang bebas kesalahan tipe secara otomatis.
• Menyiapkan halaman dokumentasi API interaktif menggunakan Scalar atau Swagger UI.
• Menguji keselarasan kontrak backend vs frontend menggunakan mock server (Prism).
• Menggantikan pemanggilan fetch() manual tanpa tipe dengan klien otomatis yang terverifikasi.

Pola Integrasi Orval & React Query di Frontend

// Penggunaan hooks otomatis hasil generate Orval di komponen React 19
import { useCreateOrder } from '@/api/generated/endpoints/orders';

export function CheckoutButton({ customerId, productId, quantity, totalCents }: Props) {
  const { mutate, isPending } = useCreateOrder({
    mutation: {
      onSuccess: (order) => {
        console.log(`Pesanan berhasil dibuat: ${order.id}`);
      },
      onError: (err) => {
        console.error('Gagal membuat pesanan:', err);
      }
    }
  });

  return (
    <button 
      onClick={() => mutate({ data: { customerId, items: [{ productId, quantity }], totalCents } })}
      disabled={isPending}
      className="rounded-lg bg-emerald-600 px-4 py-2 font-medium text-white transition hover:bg-emerald-500"
    >
      {isPending ? 'Memproses...' : 'Bayar Sekarang'}
    </button>
  );
}

Validasi Spectral di Pipeline CI/CD

# .spectral.yaml
extends: ["spectral:oas"]
rules:
  operation-operationId-valid-in-url: error
  operation-description: warn
  no-eval-in-markdown: error

Integrasi Orkestrasi

• api-design-expert: Menetapkan aturan penamaan endpoint, HTTP methods, dan struktur error standar.
• spec-driven-development-expert: Mengintegrasikan OpenAPI dengan pipeline otomatisasi kode.
• tanstack-query-expert: Mengelola status caching dan query invalidation di frontend.
• ci-cd-devops-architect: Menjalankan pengujian kepatuhan kontrak pada setiap Pull Request.