OpenAPI dan Swagger: Dokumentasi yang Bisa Dieksekusi

Blueprint yang bisa dites langsung

Blueprint rumah bukan sekadar gambar; kontraktor bisa mengukurnya dan tukang bisa membangun darinya. OpenAPI adalah "blueprint" untuk API: file YAML/JSON yang mendeskripsikan setiap endpoint, parameter, dan response secara terstruktur. Dari satu file ini bisa di-generate: halaman dokumentasi interaktif (Swagger UI), kode klien otomatis, bahkan mock server untuk testing.

Kenapa OpenAPI menjadi standar industri

Dokumentasi teks biasa cepat basi karena ditulis terpisah dari kode. Spesifikasi OpenAPI bisa di-generate DARI kode (atau ditulis dulu lalu di-generate kodenya, disebut contract-first), sehingga dokumentasi dan implementasi sulit berpisah. Tim frontend bisa generate TypeScript client otomatis; tim QA bisa generate test; semua dari satu sumber kebenaran.

Contoh 1: cuplikan spesifikasi

openapi: 3.0.0
info:
  title: API Toko Kopi
  version: 1.0.0
paths:
  /produk/{id}:
    get:
      summary: Ambil satu produk
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Produk ditemukan
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: integer }
                  nama: { type: string }
        "404":
          description: Produk tidak ditemukan

Satu file ini mendefinisikan endpoint, parameter, dan dua kemungkinan response lengkap dengan tipenya.

Contoh 2: dari spesifikasi ke kode

Dengan spesifikasi di atas, perintah satu baris menggenerate klien:

npx openapi-typescript spesifikasi.yaml -o api.d.ts

Hasilnya tipe TypeScript otomatis: Api["/produk/{id}"]["get"]. Frontend mendapat autocomplete dan type-checking gratis. Ubah spesifikasi, regenerate, dan semua kode yang memakai endpoint lama langsung error di type-check: refactoring API menjadi aman.

Kesalahan umum

Salah: menulis spec manual lalu tidak pernah update. Sama basi dengan dokumentasi teks. Yang benar: generate dari kode (Laravel Scribe, swagger-jsdoc) atau jadikan spec sebagai kontrak yang di-test otomatis.

Salah: spec terlalu longgar (semua any/object). Generate kode tidak berguna. Yang benar: definisikan schema sepresisi mungkin, pakai enum dan required dengan benar.

Salah: tidak memvalidasi request terhadap spec. Spec hanya pajangan. Yang benar (level lanjut): pakai middleware validasi yang menolak request tidak sesuai spec.

Ekosistem OpenAPI dalam satu paragraf

Satu file spesifikasi, banyak kegunaan: Swagger UI me-render dokumentasi interaktif yang bisa di-try-out; Redoc menghasilkan tampilan dokumentasi yang cantik untuk publik; Prism menjadi mock server sehingga frontend bisa coding sebelum backend jadi; generator seperti openapi-typescript membuat tipe otomatis. Alur kerja modern: tulis spec dulu (contract-first), generate mock untuk frontend, generate tipe untuk type-safety, lalu implementasikan backend sesuai kontrak. Satu sumber kebenaran untuk seluruh tim.

Catatan teknis: Ekosistem OpenAPI luas: Swagger UI (dokumentasi interaktif), Redoc (tampilan cantik), Prism (mock server), dan generator untuk puluhan bahasa. Mulai dari Swagger UI: paste spec-mu dan langsung dapat dokumentasi yang bisa di-"try it out".