Hasilkan OpenAPI dari perilaku dengan Claude Code — jujur

Mengapa kontrak OpenAPI bisa bergeser (dan kenapa hal itu penting)

Kontrak OpenAPI adalah deskripsi bersama tentang API Anda: endpoint apa yang ada, apa yang Anda kirim, apa yang diterima kembali, dan seperti apa error. Ini adalah perjanjian antara server dan siapa pun yang memanggilnya (aplikasi web, aplikasi mobile, atau layanan lain).

Masalahnya adalah pergeseran. API yang berjalan berubah, tapi spec tidak. Atau spec “dirapikan” supaya terlihat lebih baik daripada kenyataan, sementara implementasi terus mengembalikan field aneh, melewatkan kode status, atau bentuk error yang tidak konsisten. Seiring waktu, orang berhenti mempercayai file OpenAPI, dan itu menjadi sekadar dokumen lain yang diabaikan.

Pergeseran biasanya muncul dari tekanan normal: perbaikan cepat dirilis tanpa memperbarui spec, field opsional baru ditambahkan "sementara", pagination berkembang, atau tim memperbarui “sumber kebenaran” yang berbeda (kode backend, koleksi Postman, dan file OpenAPI).

Menjaga kejujuran berarti spec cocok dengan perilaku nyata. Jika API kadang mengembalikan 409 untuk konflik, itu harus ada di kontrak. Jika field bisa null, sebutkan. Jika auth diperlukan, jangan biarkan kabur.

Alur kerja yang baik meninggalkan Anda dengan:

• File OpenAPI yang mencerminkan perilaku yang dimaksud dan yang diamati
• Sekumpulan pemeriksaan sederhana untuk menangkap drift lebih dini, sebelum klien rusak
• Contoh validasi klien dan server konkret yang bisa Anda salin ke codebase

Poin terakhir penting karena kontrak hanya membantu ketika ditegakkan. Spec yang jujur ditambah pemeriksaan yang dapat diulang mengubah “dokumentasi API” menjadi sesuatu yang tim bisa andalkan.

Mulai dari perilaku yang dimaksud, bukan dari kode

Jika Anda mulai dengan membaca kode atau menyalin rute, OpenAPI Anda akan menggambarkan apa yang ada hari ini, termasuk kekhasan yang mungkin tidak ingin Anda janjikan. Sebaliknya, jelaskan apa yang seharusnya API lakukan untuk pemanggil, lalu gunakan spec untuk memverifikasi implementasi cocok.

Sebelum menulis YAML atau JSON, kumpulkan sekumpulan fakta kecil per endpoint:

• Apa yang dilakukannya (method dan path)
• Apa yang diterima (headers, query, path params, body)
• Apa yang dikembalikan (kode status sukses, bentuk respons, header penting)
• Apa yang bisa gagal (error yang mungkin, kode status, bentuk body error)
• Siapa yang bisa memanggilnya (auth dan peran, jika relevan)

Lalu tulis perilaku sebagai contoh. Contoh memaksa Anda menjadi spesifik dan membuatnya lebih mudah menyusun kontrak yang konsisten.

Untuk API Tasks, contoh happy path bisa: “Buat task dengan title dan dapatkan kembali id, title, status, dan createdAt.” Tambahkan kegagalan umum: “Missing title mengembalikan 400 dengan {\"error\":\"title is required\"}” dan “Tidak ada auth mengembalikan 401.” Jika Anda sudah tahu edge case, sertakan: apakah judul duplikat diizinkan, dan apa yang terjadi ketika ID task tidak ada.

Tangkap aturan sebagai kalimat sederhana yang tidak bergantung pada detail kode:

• “title wajib dan 1-120 karakter.”
• “List mengembalikan hingga 50 item kecuali limit diatur (maks 200).”
• “dueDate adalah date-time ISO 8601.”
• “Endpoint tulis memerlukan token pengguna.”

Terakhir, tentukan scope v1 Anda. Jika ragu, jaga v1 kecil dan jelas (create, read, list, update status). Simpan pencarian, bulk updates, dan filter kompleks untuk nanti agar kontrak tetap dapat dipercaya.

Template ringan untuk mendeskripsikan endpoint

Sebelum Anda meminta Claude Code menulis spec, tulis catatan perilaku dalam format kecil yang dapat diulang. Tujuannya membuatnya sulit untuk “mengisi celah” dengan tebakan.

Template yang baik cukup pendek sehingga Anda benar-benar menggunakannya, tapi konsisten sehingga dua orang akan menggambarkan endpoint yang sama dengan cara yang mirip. Fokuskan pada apa yang API lakukan, bukan bagaimana diimplementasikan.

Template catatan perilaku endpoint

Gunakan satu blok per endpoint:

METHOD + PATH:
Purpose (1 sentence):
Auth:
Request:
- Query:
- Headers:
- Body example (JSON):
Responses:
- 200 OK example (JSON):
- 4xx example (status + JSON):
Edge cases:
Data types (human terms):

Tulis setidaknya satu request konkret dan dua respons. Sertakan kode status dan body JSON realistis dengan nama field aktual. Jika sebuah field opsional, tunjukkan satu contoh saat field itu hilang.

Sebutkan edge case secara eksplisit. Ini tempat di mana spec diam-diam menjadi tidak benar nanti karena setiap orang mengasumsikan hal berbeda: hasil kosong, ID tidak valid (400 vs 404), duplikat (409 vs perilaku idempoten), kegagalan validasi, dan batas pagination.

Juga catat tipe data dengan kata-kata biasa sebelum berpikir tentang skema: string vs number, format date-time, boolean, dan enum (daftar nilai yang diizinkan). Ini mencegah skema “cantik” yang tidak cocok dengan payload nyata.

Draft spec OpenAPI dengan Claude Code (prompt yang bekerja)

Claude Code bekerja paling baik ketika Anda memperlakukannya seperti juru tulis yang teliti. Beri ia catatan perilaku dan aturan ketat untuk bagaimana OpenAPI harus dibentuk. Jika Anda hanya mengatakan “tulis spec OpenAPI,” biasanya Anda akan mendapatkan tebakan, penamaan yang tidak konsisten, dan kasus error yang hilang.

Tempelkan catatan perilaku Anda terlebih dahulu, lalu tambahkan blok instruksi ketat. Prompt praktis terlihat seperti ini:

You are generating an OpenAPI 3.1 YAML spec.
Source of truth: the behavior notes below. Do not invent endpoints or fields.
If anything is unclear, list it under ASSUMPTIONS and leave TODO markers in the spec.

Requirements:
- Include: info, servers (placeholder), tags, paths, components/schemas, components/securitySchemes.
- For each operation: operationId, tags, summary, description, parameters, requestBody (when needed), responses.
- Model errors consistently with a reusable Error schema and reference it in 4xx/5xx responses.
- Keep naming consistent: PascalCase schema names, lowerCamelCase fields, stable operationId pattern.

Behavior notes:
[PASTE YOUR NOTES HERE]

Output only the OpenAPI YAML, then a short ASSUMPTIONS list.

Setelah Anda mendapat draf, baca ASSUMPTIONS terlebih dahulu. Di situlah kejujuran dimenangkan atau hilang. Setujui apa yang benar, perbaiki yang salah, lalu jalankan ulang dengan catatan yang diperbarui.

Untuk menjaga penamaan konsisten, nyatakan konvensi di awal dan patuhi. Misalnya: pola operationId yang stabil, nama tag hanya kata benda, nama schema tunggal, satu Error bersama, dan satu nama skema auth yang dipakai di mana-mana.

Jika Anda bekerja di workspace vibe-coding seperti Koder.ai, akan membantu menyimpan YAML sebagai file nyata lebih awal dan beriterasi dalam diff kecil. Anda dapat melihat perubahan mana berasal dari keputusan perilaku yang disetujui versus detail yang ditebak model.

Validasi spec sebelum membandingkan dengan API yang berjalan

Sebelum Anda membandingkan apa pun dengan produksi, pastikan file OpenAPI konsisten secara internal. Ini tempat tercepat untuk menangkap pemikiran yang berharap dan kata-kata yang kabur.

Baca tiap endpoint seolah Anda pengembang klien. Fokus pada apa yang pemanggil harus kirim dan apa yang bisa mereka andalkan untuk diterima kembali.

Langkah tinjau praktis:

• Required vs optional: tandai field yang wajib dengan benar dan hindari “semua optional.”
• Tipe dan format: jelaskan UUID, email, date-time, nilai min/max.
• Contoh: tambahkan setidaknya satu contoh request dan response realistis per endpoint, dan jaga contoh konsisten dengan skema.
• Kode status: selaraskan dengan catatan perilaku (create sering 201, bukan 200). Pilih 400 vs 422 dan konsisten.
• Auth: nyatakan apa yang diperlukan per endpoint, dan apakah peran mempengaruhi akses.

Respons error perlu perhatian ekstra. Pilih satu bentuk bersama dan gunakan ulang di mana-mana. Beberapa tim menjaga sangat sederhana ({ error: string }), yang lain memakai objek ({ error: { code, message, details } }). Keduanya bisa bekerja, tapi jangan mencampurnya di berbagai endpoint dan contoh. Jika Anda mencampurnya, kode klien akan menumpuk kasus khusus.

Skenario sanity cepat membantu. Jika POST /tasks mengharuskan title, skema harus menandainya required, respons kegagalan harus menunjukkan body error yang sebenarnya Anda kembalikan, dan operasi harus jelas menyatakan apakah auth diperlukan.

Bandingkan spec dengan implementasi API yang berjalan

Setelah spec terbaca seperti perilaku yang dimaksud, anggap API yang berjalan sebagai kebenaran tentang apa yang klien alami hari ini. Tujuannya bukan “menang” antara spec dan kode. Tujuannya memunculkan perbedaan lebih awal dan membuat keputusan yang jelas pada tiap perbedaan.

Untuk pass pertama, sampel request/response nyata biasanya opsi paling sederhana. Logs dan tes otomatis juga bekerja jika dapat dipercaya.

Perhatikan mismatch umum: endpoint yang ada di satu tempat tapi tidak di tempat lain, perbedaan nama field atau bentuk, perbedaan kode status (200 vs 201, 400 vs 422), perilaku yang tidak didokumentasikan (pagination, sorting, filtering), dan perbedaan auth (spec mengatakan publik, kode memerlukan token).

Contoh: OpenAPI Anda menyatakan POST /tasks mengembalikan 201 dengan {id,title}. Anda memanggil API berjalan dan mendapatkan 200 plus {id,title,createdAt}. Itu bukan “cukup dekat” jika Anda menggenerasi SDK klien dari spec.

Sebelum mengedit apa pun, putuskan cara menyelesaikan konflik:

• Jika perilaku benar tapi tidak terdokumentasi, perbarui spec.
• Jika spec adalah kontrak yang disepakati, perbaiki kode agar cocok.
• Jika tidak ada yang benar, sesuaikan perilaku yang dimaksud dulu, lalu perbarui keduanya.

Jaga setiap perubahan kecil dan dapat ditinjau: satu endpoint, satu respons, satu tweak skema. Lebih mudah ditinjau dan lebih mudah dites ulang.

Hasilkan contoh validasi klien dan server dari kontrak

Setelah Anda punya spec yang dapat dipercaya, ubah menjadi contoh validasi kecil. Inilah yang mencegah drift kembali menyelinap.

Validasi sisi server (tolak request buruk)

Di server, validasi berarti gagal cepat ketika request tidak cocok kontrak, dan mengembalikan error yang jelas. Itu melindungi data Anda dan membuat bug lebih mudah ditemukan.

Cara sederhana mengekspresikan contoh validasi server adalah menulisnya sebagai kasus dengan tiga bagian: input, output yang diharapkan, dan error yang diharapkan (kode error atau pola pesan, bukan teks persis).

Contoh (kontrak mengatakan title wajib dan harus 1 sampai 120 karakter):

{
  "name": "Create task without title returns 400",
  "request": {"method": "POST", "path": "/tasks", "body": {"title": ""}},
  "expect": {"status": 400, "body": {"error": {"code": "VALIDATION_ERROR"}}}
}

Validasi sisi klien (tangkap perubahan yang merusak lebih awal)

Di klien, validasi adalah tentang mendeteksi drift sebelum pengguna merasakannya. Jika server mulai mengembalikan bentuk berbeda, atau field wajib menghilang, tes Anda harus menandainya.

Fokus pemeriksaan klien pada apa yang benar-benar Anda andalkan, seperti “sebuah task punya id, title, status.” Hindari menegaskan setiap field optional atau urutan yang tepat. Anda ingin gagal pada perubahan yang merusak, bukan pada penambahan yang tidak berbahaya.

Beberapa pedoman supaya tes tetap mudah dibaca:

• Lebih suka memeriksa keberadaan dan tipe daripada nilai persis.
• Tegaskan field yang wajib saja kecuali field optional penting untuk fitur Anda.
• Untuk error, periksa status dan kode error, bukan pesan lengkap.
• Izinkan field tambahan kecuali kontrak secara eksplisit melarangnya.

Jika Anda membangun dengan Koder.ai, Anda bisa menghasilkan dan menyimpan contoh kasus ini berdampingan dengan file OpenAPI, lalu memperbaruinya sebagai bagian dari review yang sama saat perilaku berubah.

Contoh skenario: API Tasks sederhana dari ujung ke ujung

Bayangkan API kecil dengan tiga endpoint: POST /tasks membuat tugas, GET /tasks men-list tugas, dan GET /tasks/{id} mengembalikan satu tugas.

Mulailah dengan menulis beberapa contoh konkret untuk satu endpoint, seolah menjelaskannya kepada tester.

Untuk POST /tasks, perilaku yang dimaksud bisa:

• Sukses: kirim { \"title\": \"Buy milk\" } dan dapatkan 201 dengan objek task baru, termasuk id, title, dan done:false.
• Gagal 1: kirim {} dan dapatkan 400 dengan error seperti { \"error\": \"title is required\" }.
• Gagal 2: kirim { \"title\": \"x\" } (terlalu pendek) dan dapatkan 422 dengan { \"error\": \"title must be at least 3 characters\" }.

Ketika Claude Code membuat draf OpenAPI, snippet untuk endpoint ini harus menangkap skema, kode status, dan contoh realistis:

paths:
  /tasks:
    post:
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            examples:
              ok:
                value: { "title": "Buy milk" }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              examples:
                created:
                  value: { "id": "t_123", "title": "Buy milk", "done": false }
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingTitle:
                  value: { "error": "title is required" }
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tooShort:
                  value: { "error": "title must be at least 3 characters" }

Satu mismatch umum bersifat halus: API berjalan mengembalikan 200 alih-alih 201, atau mengembalikan { "taskId": 123 } bukan { "id": "t_123" }. Itu jenis perbedaan “hampir sama” yang memecahkan klien yang digenerasi.

Perbaiki dengan memilih satu sumber kebenaran. Jika perilaku yang dimaksud benar, ubah implementasi supaya mengembalikan 201 dan bentuk Task yang disepakati. Jika perilaku produksi sudah diandalkan, perbarui spec (dan catatan perilaku) untuk mencerminkan kenyataan, lalu tambahkan validasi dan respons error yang hilang agar klien tidak terkejut.

Kesalahan umum yang membuat kontrak tidak jujur

Kontrak menjadi tidak jujur ketika ia berhenti mendeskripsikan aturan dan mulai mendeskripsikan apa pun yang API Anda kembalikan pada satu hari yang baik. Tes sederhana: apakah implementasi baru bisa lolos spec ini tanpa menyalin kekhasan hari ini?

Satu jebakan adalah overfitting. Anda menangkap satu respons dan mengubahnya menjadi hukum. Contoh: API Anda saat ini selalu mengembalikan dueDate: null, jadi spec mengatakan field selalu nullable. Padahal aturan nyata mungkin “diperlukan ketika status scheduled.” Kontrak harus mengekspresikan aturan, bukan sekadar dataset saat ini.

Error seringkali tempat kejujuran rusak. Godaan untuk menspesifikasi hanya respons sukses karena terlihat bersih. Tapi klien perlu dasar: 401 saat token hilang, 403 untuk akses terlarang, 404 untuk ID yang tidak dikenal, dan error validasi yang konsisten (400 atau 422).

Polanya lain yang menyebabkan masalah:

• Nama dan tipe bergeser antar endpoint (taskId di satu rute tapi id di tempat lain, atau priority sebagai string di satu respons dan number di respons lain).
• Contoh bertentangan dengan skema (nilai enum tidak cocok, contoh date-time bukan ISO 8601).
• Tipe dilebarkan untuk menghindari keputusan (semuanya jadi string, semuanya jadi optional).
• Spec terdengar seperti copy marketing ("fast", "secure") alih-alih kontrak yang bisa dites.

Kontrak yang baik bisa dites. Jika Anda tidak bisa menulis tes yang gagal dari spec, itu belum jujur.

Pemeriksaan cepat sebelum Anda membagikan atau mempublikasikan file OpenAPI

Sebelum Anda menyerahkan file OpenAPI ke tim lain (atau menempelkannya ke docs), lakukan pemeriksaan cepat: "bisakah seseorang menggunakan ini tanpa membaca pikiran Anda?"

Mulai dari contoh. Spec bisa valid tapi tetap tidak berguna jika setiap request dan response terlalu abstrak. Untuk tiap operasi, sertakan setidaknya satu contoh request realistis dan satu contoh respons sukses. Untuk error, satu contoh per kegagalan umum (auth, validasi) biasanya cukup.

Lalu periksa konsistensi. Jika satu endpoint mengembalikan { "error": "..." } dan endpoint lain mengembalikan { "message": "..." }, klien harus menulis logika bercabang di mana-mana. Pilih satu bentuk error dan gunakan ulang, beserta kode status yang dapat diprediksi.

Daftar pemeriksaan singkat:

• Field required, format (email, uuid, date-time), dan enum eksplisit.
• Kode status sengaja dan konsisten antar endpoint serupa.
• Respons error menyertakan skema dan contoh, bukan hanya status.
• Anda menjalankan 2-3 panggilan nyata per endpoint (tes, curl, Postman, atau logs) dan membandingkan payload dengan spec.
• Anda bisa menulis satu panggilan klien kecil dari spec saja tanpa menebak header, nama field, atau nullability.

Trik praktis: pilih satu endpoint, pura-pura Anda belum pernah melihat API, dan jawab “Apa yang saya kirim, apa yang saya dapatkan kembali, dan apa yang bisa rusak?” Jika OpenAPI tidak bisa menjawab dengan jelas, itu belum siap.

Langkah selanjutnya: jadikan kebiasaan (dan jaga perubahan tetap aman)

Alur kerja ini berbuah ketika dijalankan secara rutin, bukan hanya saat rilis panik. Pilih aturan sederhana dan patuhi: jalankan setiap kali endpoint berubah, dan jalankan lagi sebelum Anda mempublikasikan spec yang diperbarui.

Sederhanakan kepemilikan. Orang yang mengubah endpoint memperbarui catatan perilaku dan draf spec. Orang kedua meninjau diff “spec vs implementasi” seperti review kode. Tim QA atau dukungan sering menjadi reviewer yang baik karena mereka cepat melihat respons yang tidak jelas dan edge case.

Perlakukan edit kontrak seperti edit kode. Jika Anda menggunakan builder berbasis chat seperti Koder.ai, ambil snapshot sebelum edit yang berisiko dan gunakan rollback bila perlu agar iterasi tetap aman. Koder.ai juga mendukung ekspor source code, yang memudahkan menyimpan spec dan implementasi berdampingan di repo.

Rutinitas yang biasanya bekerja tanpa memperlambat tim:

• Tulis catatan perilaku saat menambah endpoint baru
• Validasi spec dan jalankan tes kontrak sebelum merge
• Bandingkan spec terhadap API yang berjalan sebelum rilis
• Ambil snapshot sebelum perubahan berisiko; rollback jika diff membingungkan

Aksi selanjutnya: pilih satu endpoint yang sudah ada. Tulis 5–10 baris catatan perilaku (input, output, kasus error), hasilkan draf OpenAPI dari catatan itu, validasi, lalu bandingkan dengan implementasi yang berjalan. Perbaiki satu mismatch, uji ulang, dan ulangi. Setelah satu endpoint, kebiasaan biasanya akan menempel.