Apa Artinya Memperlakukan Spesifikasi API Anda Sebagai Kode?

Kontrak API Anda mungkin berada di tiga tempat sekaligus. Diagram di wiki. Koleksi Postman yang diekspor seseorang pada kuartal lalu. Dokumen Markdown yang ditulis tangan yang menyimpang dari layanan yang berjalan dua rilis yang lalu. Ketika ketiganya tidak sesuai, tim Anda menebak-nebak. Tebakan dapat merusak integrasi.

Memperlakukan spesifikasi API Anda sebagai kode dapat memperbaikinya. Anda menulis satu file OpenAPI, melakukan commit ke Git, dan meninjaunya seperti file sumber lainnya. Dari satu file tersebut, Anda menghasilkan mock, pengujian, dokumentasi, dan SDK. Spesifikasi tidak lagi menjadi sesuatu yang dipikirkan belakangan dan menjadi kontrak yang digunakan semua orang sebagai dasar pengembangan.

Panduan ini menjelaskan apa arti spesifikasi-sebagai-kode, mengapa file OpenAPI layak mendapatkan ketelitian yang sama dengan kode aplikasi Anda, dan bagaimana menjalankan alur kerja tanpa harus berjuang dengan alat Anda.

Apa arti spesifikasi-sebagai-kode

Spesifikasi-sebagai-kode berarti definisi API Anda adalah file teks biasa yang disimpan dalam kontrol versi. Bukan catatan database. Bukan dokumen yang di-hosting dengan tautan berbagi. Sebuah file yang bisa Anda git diff, `branch`, dan `merge`.

Ide ini diambil langsung dari dokumentasi-sebagai-kode (docs-as-code), di mana dokumentasi berada di repositori yang sama dengan kode yang dijelaskannya dan dikirimkan melalui pipeline yang sama. Spesifikasi-sebagai-kode menerapkan disiplin yang sama pada kontrak API itu sendiri. Dokumen OpenAPI (YAML atau JSON) adalah artefak utamanya. Segala sesuatu lainnya yang berada di hilir dihasilkan darinya.

Pergeseran tersebut memiliki satu konsekuensi besar. Spesifikasi menjadi satu-satunya sumber kebenaran. Ketika seorang pengembang ingin tahu apa yang dikembalikan oleh /users/{id}, mereka membaca spesifikasi, bukan halaman wiki yang usang. Ketika QA menulis pengujian, mereka memastikan kesesuaian dengan spesifikasi. Ketika mitra berintegrasi, mereka mengambil SDK yang dihasilkan dari spesifikasi. Satu file, banyak keluaran.

Mengapa memperlakukan spesifikasi seperti kode

Setelah spesifikasi menjadi file di Git, Anda mewarisi setiap alur kerja yang sudah Anda percaya untuk kode sumber.

Tinjauan dalam pull request. Perubahan pada endpoint muncul sebagai perbedaan (diff) dalam PR. Peninjau melihat dengan tepat bidang mana yang berubah, kode status mana yang ditambahkan, dan apakah bentuk respons melanggar kompatibilitas mundur. Perubahan yang merusak tidak lagi menjadi kejutan dalam produksi. Ini menjadi utas komentar sebelum penggabungan (merge). Ini adalah inti dari alur kerja API yang berbasis Git.

Format yang ramah perbedaan. YAML biasa menghasilkan perbedaan yang bersih. Anda dapat membaca perubahan lima baris dan memahaminya dalam hitungan detik. Bandingkan itu dengan ekspor biner atau alat yang di-hosting di mana “apa yang berubah” tidak terlihat. Dengan spesifikasi di Git, `blame`, riwayat, dan perbedaan semuanya berjalan dengan baik.

Pembuatan versi yang sesungguhnya. Setiap perubahan memiliki commit, penulis, dan stempel waktu. Anda dapat memberi tag pada rilis, membuat branch untuk redesain v2, dan mengembalikan perubahan yang buruk dengan satu perintah. Riwayat API Anda menjadi dapat diaudit. Untuk melihat lebih dalam strategi penandaan (tagging) dan percabangan (branching), lihat kontrol versi OpenAPI dengan Git.

Satu sumber kebenaran. Karena mock, pengujian, dan dokumentasi semuanya berasal dari file yang sama, mereka tidak dapat menyimpang secara independen. Perbarui spesifikasi, buat ulang, dan setiap keluaran tetap konsisten.

Berikut perbandingan kedua pendekatan ini dalam praktiknya.

OpenAPI sebagai artefak

OpenAPI adalah format yang jelas untuk spesifikasi karena didukung secara luas dan dapat dibaca oleh mesin. Bagian kecil namun lengkap dari file OpenAPI 3.1 yang akan Anda simpan di repo Anda.

openapi: 3.1.0
info:
 title: Orders API
 version: 1.2.0
paths:
 /orders/{orderId}:
 get:
 summary: Get an order by ID
 operationId: getOrder
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 format: uuid
 responses:
 "200":
 description: The requested order
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"
 "404":
 description: Order not found
components:
 schemas:
 Order:
 type: object
 required: [id, status, total]
 properties:
 id:
 type: string
 format: uuid
 status:
 type: string
 enum: [pending, shipped, delivered]
 total:
 type: number
 format: float

File ini adalah kontraknya. Tambahkan bidang ke Order, dan perbedaannya adalah satu baris. Ubah enum status, dan peninjau akan langsung melihatnya. Simpan di bawah api/openapi.yaml di samping kode layanan Anda, dan spesifikasi akan menyertai implementasi yang dijelaskannya.

Spesifikasi dan dokumentasi

Manfaat dari satu file sumber adalah semua yang Anda hasilkan darinya.

Mock. Arahkan server mock ke spesifikasi dan Anda akan mendapatkan API yang dapat dijalankan sebelum satu pun endpoint dibuat. Tim frontend dan seluler mulai berintegrasi dengan kontrak sejak hari pertama. Ketika spesifikasi berubah, mock juga berubah.

Pengujian. Hasilkan pengujian kontrak yang memastikan bahwa layanan yang aktif sesuai dengan spesifikasi. Jika endpoint yang di-deploy mengembalikan bidang yang tidak pernah dideklarasikan oleh spesifikasi, pengujian akan gagal. Ini menangkap penyimpangan antara kontrak dan kode yang berjalan sebelum pelanggan menyadarinya.

Dokumentasi. Render spesifikasi menjadi dokumentasi referensi secara otomatis. Tidak ada lagi yang menulis tabel endpoint secara manual. Dokumentasi sesuai dengan spesifikasi karena dokumentasi adalah spesifikasi itu sendiri, yang dirender.

SDK. Hasilkan pustaka klien dalam berbagai bahasa dari file yang sama. Mitra mendapatkan SDK yang terketik (typed) yang selalu mencerminkan kontrak saat ini.

Setiap keluaran adalah fungsi dari spesifikasi. Ubah inputnya, hasilkan ulang keluarannya, dan konsistensi akan didapatkan secara gratis.

Bagaimana Apidog menjadikan spesifikasi sebagai sumber kebenaran

Menjalankan spesifikasi-sebagai-kode secara manual berarti menggabungkan CLI, server mock, generator dokumentasi, dan Git hook. Apidog menyatukan itu menjadi satu alur kerja.

Mode Prioritas Spesifikasi (Spec-First Mode) Apidog memperlakukan file OpenAPI Anda sebagai definisi yang otoritatif. Anda merancang endpoint berdasarkan spesifikasi, dan Apidog menjaga agar mock, pengujian, dan dokumentasi Anda selalu selaras dengannya.

Bagian yang membuat ini praktis adalah sinkronisasi Git dua arah. Apidog dapat membaca file OpenAPI Anda dari repositori dan menulis perubahan kembali ke sana, sehingga file di Git dan proyek di Apidog tetap selaras. Desain secara visual ketika itu lebih cepat, edit YAML secara langsung ketika itu lebih cepat, dan kedua jalur tersebut akan berakhir pada file yang di-commit yang sama. Itu menjaga alur tinjauan PR Anda tetap utuh sambil memberikan editor yang lebih kaya kepada tim Anda. Untuk mekanisme mendorong perubahan spesifikasi ke hulu, lihat cara menyinkronkan spesifikasi OpenAPI Anda ke GitHub.

Hasilnya: file OpenAPI tetap menjadi satu-satunya sumber kebenaran, dan alat bantu visual berada di atasnya alih-alih menggantikannya.

Kesalahan umum

Spesifikasi-sebagai-kode cukup sederhana, tetapi beberapa jebakan seringkali menjebak tim di awal.

Penyimpangan antara spesifikasi dan implementasi. Menulis spesifikasi saja tidak cukup. Jika tidak ada yang memeriksa apakah layanan yang berjalan sesuai dengannya, keduanya akan menyimpang secara diam-diam. Tambahkan pengujian kontrak ke CI agar ketidaksesuaian menyebabkan kegagalan build, bukan pelanggan.

Kebingungan antara yang dihasilkan secara otomatis versus yang ditulis tangan. Putuskan apakah spesifikasi dihasilkan dari anotasi kode atau ditulis tangan sebagai sumber. Mencampur keduanya menyebabkan file di mana tidak ada yang tahu bagian mana yang otoritatif. Pilih satu arah. Jika spesifikasi adalah sumber kebenaran Anda, perlakukan anotasi kode sebagai hal yang Anda periksa terhadapnya, bukan salinan master kedua.

Memperlakukan spesifikasi sebagai dokumentasi, bukan kontrak. Spesifikasi yang hanya Anda baca adalah dokumen. Spesifikasi yang Anda gunakan untuk menghasilkan mock, pengujian, dan SDK adalah kontrak. Nilainya berasal dari menghubungkan keluaran, bukan dari keberadaan file itu sendiri.

Melewatkan tinjauan. Spesifikasi di Git yang digabungkan tanpa tinjauan hanyalah sebuah file di Git. Intinya adalah pull request. Wajibkan tinjauan atas perubahan spesifikasi dengan cara yang sama seperti yang Anda lakukan untuk kode.

Memulai

Anda dapat mengadopsi spesifikasi-sebagai-kode secara bertahap.

1. Commit spesifikasi Anda. Pindahkan file OpenAPI Anda ke repositori pada jalur yang diketahui, seperti api/openapi.yaml.
2. Wajibkan tinjauan PR. Buat perubahan spesifikasi melewati gerbang tinjauan yang sama seperti kode. Perbedaan (diff) menjadi bahan diskusi.
3. Hasilkan satu keluaran. Mulai dengan mock atau dokumentasi. Hubungkan spesifikasi ke generator agar keluaran diperbarui saat file berubah.
4. Tambahkan pemeriksaan CI. Lakukan linting spesifikasi pada setiap PR. Tangkap OpenAPI yang tidak valid sebelum penggabungan.
5. Tutup lingkaran dengan pengujian kontrak. Setelah mock dan dokumentasi mengalir, tambahkan pengujian yang memastikan layanan yang aktif sesuai dengan spesifikasi.

Setiap langkah berdiri sendiri. Anda mendapatkan nilai pada langkah pertama dan melipatgandakannya dengan setiap penambahan.

Pergeseran ini kecil untuk dijelaskan namun besar dampaknya. Satu file, di Git, ditinjau seperti kode, menghasilkan segala sesuatu di hilir. Jika Anda menginginkan pengeditan visual dan sinkronisasi Git yang sudah terpasang, cobalah Mode Prioritas Spesifikasi Apidog dan biarkan file OpenAPI tetap menjadi satu-satunya sumber kebenaran Anda.

FAQ

Apakah “spesifikasi API sebagai kode” sama dengan “dokumentasi sebagai kode”?

Keduanya berbagi filosofi yang sama: menyimpan artefak dalam kontrol versi dan mengirimkannya melalui pipeline normal Anda. Dokumentasi-sebagai-kode menerapkannya pada dokumentasi. Spesifikasi-sebagai-kode menerapkannya pada kontrak API itu sendiri. Dalam praktiknya, keduanya saling menguatkan, karena dokumentasi yang dihasilkan dari spesifikasi yang di-commit secara definisi adalah dokumentasi-sebagai-kode.

Format apa yang harus digunakan file spesifikasi?

OpenAPI dalam format YAML adalah pilihan umum. YAML menghasilkan perbedaan yang bersih dalam pull request dan dapat dibaca oleh manusia, sementara masih dapat diurai oleh mesin untuk menghasilkan mock, pengujian, dan SDK. JSON juga berfungsi, tetapi YAML cenderung menghasilkan perbedaan yang lebih rapi.

Bagaimana cara menghentikan spesifikasi agar tidak menyimpang dari API yang sebenarnya?

Tambahkan pengujian kontrak ke CI yang memastikan layanan yang berjalan sesuai dengan spesifikasi yang di-commit. Jika sebuah endpoint mengembalikan bidang yang tidak dideklarasikan atau menghilangkan yang terdokumentasi, build akan gagal. Lingkaran umpan balik itulah yang mengubah spesifikasi dari dokumen harapan menjadi kontrak yang ditegakkan.