Dua insinyur di tim yang sama merilis dua endpoint di minggu yang sama. Yang satu mengembalikan created_at, yang lainnya mengembalikan createdAt. Yang satu memaginasi dengan ?page=2, yang lainnya dengan ?offset=20. Yang satu menempatkan kesalahan dalam objek error tingkat atas, yang lainnya menyisipkan string message. Keduanya lolos tinjauan kode, karena peninjau membaca logika, bukan penamaan. Enam bulan kemudian, antarmuka API Anda terlihat seperti ditulis oleh lima perusahaan berbeda, dan setiap integrasi klien memerlukan kasus khusus.
Linter OpenAPI ada untuk menangkap penyimpangan tersebut sebelum dirilis. Linter membaca dokumen OpenAPI Anda, menjalankannya terhadap serangkaian aturan (operasi membutuhkan deskripsi, skema membutuhkan contoh, nama properti mengikuti konvensi huruf, setiap respons mendeklarasikan tipe media), dan menggagalkan build ketika sebuah aturan dilanggar. Ini adalah ide yang sama dengan ESLint untuk JavaScript atau RuboCop untuk Ruby, tetapi ditujukan pada kontrak API Anda alih-alih kode aplikasi Anda. Jika Anda pernah berharap tinjauan desain API dapat diotomatisasi seperti pemformatan kode, itulah persisnya yang dilakukan linter.
Apa yang Sebenarnya Diperiksa oleh Linter OpenAPI
Sebuah linter beroperasi pada file spesifikasi, bukan pada server yang berjalan. Arahkan ke openapi.yaml dan linter akan menelusuri setiap path, operasi, parameter, skema, dan respons, menerapkan aturan satu per satu. Aturan-aturan ini terbagi dalam beberapa kategori.
Validitas. Apakah ini bahkan dokumen OpenAPI yang sah? Apakah setiap $ref berhasil di-resolve? Apakah kata kunci yang diperlukan ada? Ini tumpang tindih dengan validasi skema biasa, dan sebagian besar linter melakukannya sebagai dasar sebelum hal lain.
Kelengkapan. Apakah setiap operasi memiliki operationId, ringkasan, dan deskripsi? Apakah setiap parameter menjelaskan dirinya sendiri? Apakah setiap skema membawa example? Ini adalah aturan yang membuat dokumentasi dan SDK yang dihasilkan benar-benar dapat digunakan, dan inilah yang paling sering dilupakan manusia.
Konsistensi. Ini adalah hadiah yang sebenarnya. Nama properti menggunakan satu konvensi huruf. Segmen path adalah kata benda jamak. Respons error berbagi satu bentuk. Setiap respons 2xx mendeklarasikan application/json. Kode status digunakan sesuai tujuan spesifikasi HTTP. Tidak satu pun dari ini adalah bug secara terpisah; bersama-sama mereka adalah perbedaan antara API yang terasa didesain dan yang terasa asal-asalan.
Gaya rumah. Konvensi Anda sendiri. Mungkin setiap endpoint harus diberi tag. Mungkin DELETE harus mengembalikan 204. Mungkin bidang khusus internal harus diberi awalan. Ini adalah aturan yang tidak dimiliki orang lain, dan kemampuan untuk menulisnya adalah yang membedakan linter yang dapat Anda hidupi dari linter yang Anda lawan.
Sebuah aturan memiliki tingkat keparahan: error, warning, info, atau hint. Error menggagalkan build; warning ditampilkan tetapi membiarkannya lolos. Dial tingkat keparahan itulah yang memungkinkan Anda mengadopsi linting pada API yang ada tanpa tenggelam dalam 4.000 pelanggaran pada hari pertama. Mulailah semuanya sebagai warning, perbaiki yang terburuk, lalu naikkan aturan menjadi error seiring berjalannya waktu. Untuk sisi konseptual mengapa aturan-aturan ini penting dan bagaimana tim menegakkannya dalam skala besar, latar belakang yang lebih dalam ada di bagaimana perusahaan-perusahaan terkemuka memastikan konsistensi desain API.
Opsi Linter OpenAPI Utama
Berikut adalah alat-alat yang patut diketahui, dengan penjelasan jujur tentang di mana setiap alat cocok.
Spectral
Spectral, dari Stoplight, adalah standar de facto. Ini adalah CLI dan pustaka open-source yang melinter OpenAPI 2.0 dan 3.x (dan AsyncAPI, serta JSON atau YAML apa pun melalui JSONPath). Ia dilengkapi dengan kumpulan aturan spectral:oas bawaan yang mencakup aturan akal sehat, dan kekuatan sebenarnya adalah aturan khusus: Anda menjelaskan apa yang harus diperiksa menggunakan selektor given gaya JSONPath plus fungsi then, semuanya dalam file YAML. Ada katalog besar fungsi bawaan (truthy, pattern, casing, length, enumeration) dan Anda dapat beralih ke JavaScript saat Anda membutuhkan logika yang tidak dapat diekspresikan oleh format deklaratif.
Kelebihan: ada di mana-mana, memiliki ekosistem aturan terbesar, ekstensi editor ada untuk VS Code dan lainnya, dan berjalan di mana pun Node berjalan. Jika Anda menginginkan satu alat yang diakui oleh seluruh industri, inilah dia. Kelemahannya adalah bahwa menulis aturan yang tidak sepele berarti mempelajari JSONPath dan, pada akhirnya, API fungsi Spectral. Kami memiliki panduan lengkap tentang itu di membangun aturan Spectral khusus dengan TypeScript jika Anda ingin mendalami penulisan.
.spectral.yaml minimal:
extends: ["spectral:oas"]
rules:
operation-operationId: error
operation-description: warn
property-casing:
description: Properties must be camelCase
given: $.components.schemas..properties[*]~
severity: error
then:
function: casing
functionOptions:
type: camel
Jalankan:
npx @stoplight/spectral-cli lint openapi.yaml
Redocly CLI
Redocly CLI menggabungkan linting dengan bundling dan pratinjau dokumen. Linternya membaca konfigurasi redocly.yaml, dilengkapi dengan seperangkat aturan bawaan, dan mendukung set aturan yang dapat dikonfigurasi ditambah plugin kustom yang ditulis dalam JavaScript. Tim yang sudah menggunakan Redocly untuk dokumentasi mendapatkan linting dalam toolchain yang sama tanpa menambahkan dependensi, dan aturan bawaan cenderung mengarah pada apa yang membuat dokumen terlihat bagus saat dirender.
Kelebihan: integrasi yang erat dengan alur kerja dokumen dan bundling, default yang layak, dan format konfigurasi yang terasa nyaman jika Anda terbiasa dengan ekosistem Redocly. Jika Anda belum berada di sana, pustaka aturan lebih kecil daripada Spectral dan cerita aturan khusus kurang terdokumentasi secara luas.
npx @redocly/cli lint openapi.yaml
Vacuum
Vacuum adalah linter yang lebih baru yang ditulis dalam Go, dibuat untuk kecepatan. Ini kompatibel dengan kumpulan aturan Spectral, jadi Anda dapat mengarahkannya ke .spectral.yaml yang sudah ada dan mendapatkan pemeriksaan yang sama berjalan jauh lebih cepat pada spesifikasi besar. Untuk monorepo dengan lusinan dokumen API besar, perbedaan waktu eksekusi sangat nyata.
Kelebihan: cepat, kompatibel dengan set aturan Spectral, biner tunggal tanpa runtime Node. Jika spesifikasi Anda kecil, peningkatan kecepatan tidak terlihat, dan ekosistem serta alat editor lebih muda daripada Spectral, jadi ini paling menarik sebagai akselerator CI daripada pilihan dari awal.
Swagger dan openapi-spec-validator
Perlu disebutkan agar Anda tidak mengacaukannya dengan linter. Swagger Editor dan swagger-cli/openapi-spec-validator memeriksa apakah sebuah dokumen adalah OpenAPI yang valid. Itu hanya validitas, bukan konsistensi atau gaya rumah. Mereka akan dengan senang hati meloloskan spesifikasi di mana setiap properti diberi nama secara berbeda, karena tidak ada dalam spesifikasi OpenAPI yang melarangnya. Validasi diperlukan, tetapi itu adalah dasar, bukan puncak. Jika Anda memilih antara alat keluarga Swagger dan platform desain lengkap, komprominya dijelaskan dalam alternatif Swagger yang juga menguji API Anda.
Pemeriksaan Waktu Desain di Apidog
Alat-alat di atas berjalan setelah Anda memiliki file. Tempat lain untuk menangkap inkonsistensi adalah sebelum file ada, saat Anda mendesain endpoint. Apidog adalah platform design-first: Anda membangun endpoint dan skema data di editor visual, dan itu menjaga proyek Anda konsisten secara internal saat Anda mengerjakannya. Skema data yang dapat digunakan kembali berarti model yang sama direferensikan di mana-mana daripada didefinisikan ulang per endpoint, yang menghilangkan seluruh kelas penyimpangan penamaan pada sumbernya. Komponen respons bersama melakukan hal yang sama untuk bentuk kesalahan.
Apidog bukanlah pengganti langsung untuk kumpulan aturan Spectral; jika Anda telah menggunakan aturan .spectral.yaml, terus jalankan aturan tersebut. Yang diubah Apidog adalah seberapa banyak yang ditemukan linter Anda sejak awal. Ketika antarmuka desain memberlakukan penggunaan kembali, linter beralih dari lautan pelanggaran menjadi penemuan sesekali. Dan karena Apidog mengimpor dan mengekspor OpenAPI 3.x standar, file yang Anda berikan kepada Spectral atau Vacuum di CI adalah artefak yang sama, sehingga kedua lapisan tersebut saling melengkapi alih-alih bersaing.
Pengaturan Linter yang Dapat Anda Jalankan Hari Ini
Pengaturan yang baik menjalankan pemeriksaan di tiga tempat, masing-masing dengan tugas yang berbeda. Editor memberikan umpan balik instan. Hook pra-commit menghentikan kesalahan yang jelas secara lokal. CI adalah gerbang yang tidak dapat dilewati siapa pun. Berikut adalah setiap lapisan.
Lapisan 1: Editor
Instal ekstensi Spectral VS Code dan tambahkan .spectral.yaml ke root repo Anda. Ekstensi ini secara otomatis mengambilnya dan menggarisbawahi pelanggaran saat Anda mengedit spesifikasi, sama seperti kesalahan ketik mendapatkan garis merah bergelombang. Ini adalah umpan balik termurah yang mungkin, karena pengembang memperbaiki masalah sebelum masalah itu menjadi commit. Tidak ada lagi yang perlu dikonfigurasi; file di repo adalah satu-satunya sumber kebenaran untuk aturan apa adanya.
Lapisan 2: Pra-commit
Tambahkan sebuah hook agar spesifikasi yang rusak tidak pernah mencapai remote. Menggunakan skrip package.json ditambah hook Git sudah cukup:
{
"scripts": {
"lint:api": "spectral lint openapi.yaml --fail-severity=error"
}
}
# .git/hooks/pre-commit (atau melalui husky)
#!/bin/sh
npm run lint:api || {
echo "Lint OpenAPI gagal. Perbaiki spesifikasi sebelum melakukan commit."
exit 1
}
Flag --fail-severity=error adalah bagian penting. Ini memberitahu linter untuk keluar dengan kode non-nol hanya pada error, sehingga peringatan masih dicetak tanpa memblokir commit. Hal ini membuat hook tetap dapat digunakan saat Anda masih mempromosikan aturan.
Lapisan 3: CI
Ini adalah gerbang yang penting, karena ini adalah gerbang yang tidak dapat dilewati oleh rekan tim dengan --no-verify. Sebuah langkah GitHub Actions:
name: API lint
on: [pull_request]
jobs:
spectral:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=error
Pekerjaan gagal ketika spesifikasi melanggar aturan tingkat kesalahan, permintaan tarik menampilkan tanda centang merah, dan penggabungan diblokir hingga seseorang memperbaikinya. Itulah seluruh mekanisme penegakan. Tidak ada dasbor, tidak ada omelan; aturannya hijau atau tidak.
Lapisan 4: Uji API yang dijelaskan spesifikasi
Linter membuktikan bahwa spesifikasi tersebut terbentuk dengan baik dan konsisten. Linter tidak mengatakan apa-apa tentang apakah API yang berjalan cocok dengan spesifikasi. Kesenjangan itulah tempat penyimpangan kontrak bersembunyi: dokumen yang dilinting dengan indah yang menjelaskan perilaku yang berhenti dihormati oleh server tiga rilis lalu. Untuk menutupnya, Anda menjalankan tes terhadap API langsung di pipeline yang sama.
Di sinilah Apidog CLI cocok di samping linter Anda. Ini adalah paket npm, apidog-cli, dan ia menjalankan skenario pengujian Apidog Anda dari baris perintah sehingga mereka masuk ke CI tepat setelah langkah lint:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
Perintah apidog run keluar dengan kode bukan nol ketika tes gagal, kontrak yang sama yang diandalkan oleh setiap langkah CI, sehingga tes yang gagal memblokir penggabungan persis seperti halnya lint yang gagal. Reporter -r junit mengeluarkan XML yang diurai dasbor CI Anda menjadi pohon pass/fail, dan -e mengarahkan skenario yang sama ke staging atau produksi tanpa menduplikasinya. CLI juga dapat import dokumen OpenAPI 3.x, sehingga file yang diperiksa linter Anda adalah file yang sama yang diuji Apidog. Untuk pola pipeline lengkap, termasuk reporter dan penanganan kode keluar, lihat panduan tentang menjalankan Apidog CLI di pipeline CI/CD Anda. Jika Anda menggunakan GitHub secara spesifik, Apidog CLI di GitHub Actions memiliki alur kerja salin-tempel.
Lint dulu, tes kedua. Langkah lint cepat dan menangkap masalah desain; langkah tes lebih lambat dan menangkap masalah perilaku. Jalankan keduanya sebagai dua tahapan dan permintaan tarik harus melewati keduanya.
Memilih dan Menerapkan Kumpulan Aturan Tanpa Rasa Sakit
Memilih alat adalah bagian yang mudah. Mengadopsinya pada API yang sudah ada adalah tempat tim-tim terhenti, karena eksekusi pertama pada spesifikasi yang matang mengembalikan ratusan pelanggaran dan reaksi yang jelas adalah mematikan semuanya.
Jangan mulai dari nol aturan dan jangan mulai dari setiap aturan sebagai error. Mulailah dari set aturan bawaan (spectral:oas) dengan semua yang Anda tambahkan diatur ke warn. Jalankan, baca jumlahnya, dan perbaiki error validitas terlebih dahulu karena itu adalah bug nyata. Kemudian pilih dua atau tiga aturan konsistensi yang paling penting bagi klien Anda (biasanya penulisan huruf properti dan satu bentuk error) dan promosikan hanya itu ke error. Semua yang lain tetap menjadi peringatan. Setiap sprint, promosikan satu atau dua peringatan lagi menjadi error saat kode base menyusul. Dalam satu kuartal seluruh set aturan ditegakkan dan tidak ada yang harus berhenti merilis untuk mencapainya.
Tulis aturan gaya internal secukupnya. Setiap aturan kustom adalah kode yang harus dipelihara dan dijelaskan kepada karyawan baru. Sebuah aturan mendapatkan tempatnya hanya ketika pelanggaran benar-benar merugikan Anda, bukan karena kemungkinan. Untuk aturan yang Anda tulis, gunakan lapisan desain agar jarang terjadi: jika skema Anda digunakan kembali dari definisi pusat, aturan penulisan huruf properti hampir tidak pernah aktif karena hanya ada satu tempat nama didefinisikan. Kerangka konseptual untuk aturan mana yang layak ditegakkan, versus mana yang tidak penting, dibahas dalam praktik terbaik desain API.
Jika Anda mendesain dalam bahasa yang berbeda dari YAML mentah, linter tetap berlaku. TypeSpec mengompilasi menjadi OpenAPI, dan Anda melinter dokumen yang dihasilkan dengan cara yang sama; linter tidak peduli bagaimana file tersebut dibuat, hanya apa yang dikatakannya.
Di Mana Linter Cocok dalam Lingkaran Desain yang Lebih Besar
Linter adalah salah satu kontrol dalam alur kerja design-first, bukan keseluruhan. Lingkaran penuhnya adalah: merancang kontrak, melinternya, membuat mock-nya agar klien dapat membangun berdasarkan itu, menguji implementasi terhadap itu, dan menerbitkan dokumen darinya. Lewati salah satu langkah dan yang lain akan kehilangan nilainya. Spesifikasi yang dilinter yang tidak di-mock oleh siapa pun masih menghambat pekerjaan frontend. Spesifikasi yang di-mock yang tidak diuji oleh siapa pun masih menyimpang dari kenyataan.
Alasan untuk menempatkan desain pertama dalam lingkaran itu adalah alasan yang sama mengapa linting berfungsi: menangkap masalah di mana mereka paling murah untuk diperbaiki. Mengubah nama properti di alat desain adalah satu pengeditan. Mengubahnya setelah tiga tim telah merilis dengan nama lama adalah migrasi. Linter menegakkan konsistensi pada file; proses design-first menegakkannya pada keputusan sebelum file ada. Jika Anda ingin argumen yang lebih luas untuk pengurutan, API-first vs API design-first vs code-first menjelaskan komprominya, dan alat desain API contract-first mencakup alat yang mendukungnya.
Apidog mencakup seluruh lingkaran itu di satu tempat: desain dengan skema yang dapat digunakan kembali, mock secara instan, uji dengan CLI di CI, dan ekspor OpenAPI bersih untuk linter mana pun yang Anda standarisasi. Linter masih memiliki tugas; hanya saja lebih sedikit yang harus ditangkap.