dokumentasiopenapiapi-designMahir4 mnt baca

Dokumentasi API: Menulis yang Bikin Orang Paham

Menyusun dokumentasi API yang lengkap dan jujur: endpoint, parameter, contoh respons, daftar error, plus pengenalan OpenAPI.

Dokumentasi adalah kontrak

API tanpa dokumentasi seperti restoran tanpa menu: pengunjung harus menebak-nebak. Dokumentasi yang bagus membuat frontend developer (termasuk dirimu di masa depan) bisa memakai API tanpa bertanya ke pembuatnya. Kabar baiknya: karena kamu sudah mempelajari HTTP dari modul 1 sampai 13, kamu sudah tahu persis apa yang perlu ditulis.

Yang wajib ada untuk setiap endpoint

Minimal, satu endpoint butuh tujuh informasi ini:

  1. Method dan URL, misalnya GET /api/artikel/:id.
  2. Deskripsi singkat: endpoint ini untuk apa.
  3. Autentikasi: butuh token atau tidak.
  4. Parameter: query string, path parameter, atau body, lengkap dengan tipe data dan mana yang wajib.
  5. Contoh request yang bisa disalin langsung.
  6. Contoh respons sukses beserta status code-nya.
  7. Daftar error yang mungkin keluar beserta artinya.

Contoh dokumentasi sederhana dalam Markdown:

markdown
## GET /api/artikel/:id

Mengambil satu artikel berdasarkan id.

**Auth:** tidak wajib (artikel publik).

**Parameter:**
- `id` (path, number, wajib): id artikel.

**Respons sukses (200):**
```json
{ "success": true, "data": { "id": 42, "judul": "Belajar HTTP" } }
```

**Error:**
- `404`: artikel dengan id tersebut tidak ditemukan.

Perhatikan contoh di atas memakai blok kode bersarang. Saat menulis dokumentasi asli, sesuaikan formatnya dengan tools yang kamu pakai.

Naik level: OpenAPI / Swagger

Untuk API yang besar, dokumentasi manual cepat basi. Standar industrinya adalah OpenAPI (dulu bernama Swagger): file YAML/JSON yang mendeskripsikan seluruh API secara terstruktur. Dari satu file itu bisa digenerate banyak hal: halaman dokumentasi interaktif (Swagger UI), kode client otomatis, bahkan testing. Banyak framework backend (termasuk Laravel dan Next.js via plugin) bisa menggenerate file OpenAPI dari kode, jadi dokumentasi selalu sinkron dengan implementasi.

Kamu tidak wajib menguasai OpenAPI sekarang, tapi ketahuilah namanya. Saat suatu hari kamu membuka dokumentasi API dan melihat tombol "Try it out" yang bisa mengirim request langsung dari browser, kemungkinan besar itu Swagger UI yang digenerate dari OpenAPI.

Dokumentasi untuk frontend-mu sendiri

Prinsip yang sama berlaku saat kamu menulis fungsi fetch di frontend: beri nama yang jelas (ambilArtikel, bukan getData2), tulis komentar singkat untuk parameter yang tidak jelas, dan catat perilaku spesial (misalnya "fungsi ini melempar error saat 401"). Kode yang menjelaskan dirinya sendiri adalah dokumentasi terbaik.

Catatan teknis: Dokumentasi yang basi (tidak sesuai perilaku API saat ini) lebih berbahaya daripada tidak ada dokumentasi sama sekali, karena membuat developer percaya pada sesuatu yang salah. Jadikan update dokumentasi bagian dari definisi "selesai" setiap kali API berubah. Kalau memakai OpenAPI yang digenerate dari kode, masalah ini berkurang drastis karena dokumentasi mengikuti kode secara otomatis.