Sebagian besar tutorial desain API dimulai dengan mouse. Buka editor visual, seret skema ke kanvas, klik dialog untuk menambahkan bidang. Itu berfungsi, tetapi tidak sesuai dengan cara banyak tim sebenarnya mengirimkan produk. Jika definisi API Anda berada di Git, ditinjau dalam pull request, dan melewati CI, Anda ingin mendesainnya dengan cara yang sama seperti Anda menyebarkannya: dari terminal, dalam teks, dengan perintah yang dapat Anda skrip.
Mendesain API dari baris perintah berarti Anda membuat kontrak, melintingnya sesuai pedoman gaya, menggabungkannya ke dalam satu file, dan menghasilkan stub, semua tanpa meninggalkan shell. Setiap langkah dapat diulang. Setiap langkah dapat berjalan dalam sebuah pipeline. Dan ketika agen AI atau rekan tim perlu mereproduksi pengaturan Anda, mereka menjalankan perintah yang sama dengan yang Anda lakukan, alih-alih menebak tombol mana yang Anda klik.
Panduan ini membahas dua rute. Pertama, jalur open-source umum yang dibangun dari alat-alat khusus: membuat file OpenAPI, melintingnya dengan Spectral, menggabungkannya dengan Redocly CLI, dan menghasilkan stub server dengan openapi-generator. Kemudian jalur CLI Apidog, di mana desain, skema, endpoint, dan otentikasi berada dalam satu proyek yang dapat Anda kelola dari terminal. Jika Anda ingin latar belakang konseptual yang lebih mendalam terlebih dahulu, baca panduan kami tentang cara mendesain API dan panduan mendalam tentang mendesain REST API.
Jika Anda mengikuti Apidog, dapatkan binernya terlebih dahulu. Panduan instalasi Apidog CLI kami mencakup langkah npm install -g apidog-cli dan jabat tangan apidog login --with-token, dan panduan Apidog CLI lengkap memetakan setiap kelompok perintah.
Rute open-source umum: membuat, melinting, menggabungkan, menghasilkan
Tumpukan desain CLI klasik adalah kumpulan alat independen yang Anda gabungkan. Anda menyimpan definisi API Anda dalam file OpenAPI di bawah kontrol versi dan menjalankan setiap alat sebagai langkah. Ini adalah alur kerja desain API Git-native, dan ini benar-benar bagus. Begini bentuknya.
Buat dokumen OpenAPI
Anda mulai dengan file YAML biasa. Tidak diperlukan editor khusus; editor teks apa pun berfungsi. File openapi.yaml minimal terlihat seperti ini:
openapi: 3.0.3
info:
title: Orders API
version: 1.0.0
paths:
/orders/{orderId}:
get:
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: An order
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
components:
schemas:
Order:
type: object
required: [id, status]
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
Seiring berkembangnya API, Anda memisahkannya ke beberapa file dan mereferensikannya dengan $ref. Ini menjaga setiap skema tetap dapat dibaca dan ditinjau secara independen.
Lint dengan Spectral
OpenAPI yang ditulis tangan cenderung melenceng. Seseorang lupa operationId, orang lain membiarkan respons tidak terdokumentasi, yang ketiga menciptakan konvensi penamaan mereka sendiri. Linter menangkap semua itu sebelum peninjauan. Spectral, dari Stoplight, adalah pilihan standar. Ini menyediakan ruleset untuk OpenAPI dan memungkinkan Anda menulis sendiri.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Spectral mencetak setiap pelanggaran dengan nomor baris dan tingkat keparahan. Anda dapat menggagalkan build karena kesalahan dengan memeriksa kode keluar di CI. Redocly CLI dan vacuum melakukan pekerjaan yang sama jika Anda menginginkan alternatif; vacuum cepat dan dapat digunakan sebagai linter yang kompatibel dengan Spectral. Intinya tetap sama terlepas dari pilihan Anda: linting adalah alat terpisah yang berdedikasi, dan Anda menjalankannya sebagai langkah tersendiri.
Gabungkan dengan Redocly CLI
Setelah definisi Anda tersebar di beberapa file, sebagian besar alat hilir menginginkan dokumen mandiri tunggal. Redocly CLI menyelesaikan setiap $ref dan meratakan pohon menjadi satu file.
npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Redocly juga melinting (redocly lint) dan menampilkan pratinjau dokumen, sehingga beberapa tim menggunakannya untuk pemeriksaan gaya dan penggabungan. Dokumen resminya mencantumkan kumpulan perintah lengkap.
Hasilkan stub dengan openapi-generator
Dengan spesifikasi yang bersih dan tergabung, Anda menghasilkan kode. openapi-generator mengubah dokumen OpenAPI menjadi stub server, SDK klien, dan lainnya di puluhan bahasa.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
-i dist/openapi.bundled.yaml \
-g spring \
-o ./server
Ganti -g spring dengan -g python-flask, -g go-server, atau generator lain yang didukung. Sekarang Anda memiliki kerangka kerja yang sesuai dengan kontrak Anda.
Itulah rute terbuka dari ujung ke ujung: empat alat, empat perintah, semuanya dapat diskrip. Biayanya adalah pengkabelan. Anda memelihara tata letak file, konfigurasi linter, langkah penggabungan, dan konfigurasi generator sendiri, dan setiap alat memiliki konvensinya sendiri. Ini berfungsi dengan baik ketika Anda menginginkan kontrol maksimum dan tidak keberatan dengan "perekat" yang menggabungkannya.
Rute Apidog CLI: desain dalam satu proyek
Pendekatan lain menyimpan desain, skema, endpoint, mock, dan otentikasi di dalam satu proyek yang Anda kelola dari terminal. Biner apidog-cli adalah CLI sumber daya proyek yang lengkap, bukan hanya test runner. Ia memiliki kelompok perintah untuk seluruh permukaan desain: schema untuk model data, endpoint untuk operasi, folder untuk organisasi, security-scheme untuk otentikasi, ditambah import, export, mock, dan banyak lagi.
Satu catatan jujur di awal: Apidog tidak melinting OpenAPI Anda atau menegakkan pedoman gaya. Bukan itu tujuannya. Jika Anda membutuhkan linting, pertahankan Spectral atau vacuum dalam pipeline Anda. Apidog juga bukan open source; ini adalah produk komersial dengan tingkatan gratis. Apa yang diberikannya kepada Anda adalah proyek terintegrasi sehingga Anda tidak perlu menyatukan bagian-bagian desain sendiri. Pandangan kami tentang alternatif Swagger untuk desain dan pengujian API mencakup di mana pertukaran itu masuk akal.
Instal dan otentikasi terlebih dahulu (lihat panduan instalasi untuk pengaturan token):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Setiap perintah mengembalikan JSON terstruktur, dan sebagian besar respons menyertakan blok agentHints.nextSteps yang memberi tahu Anda (atau agen) apa yang harus dijalankan selanjutnya. Tambahkan --help ke perintah apa pun untuk melihat flag-nya secara detail.
Definisikan model data dengan apidog schema
Desain dimulai dengan data Anda. Skema Order yang dapat digunakan kembali menjadi satu-satunya sumber kebenaran yang direferensikan oleh endpoint, ide yang sama dengan components/schemas di OpenAPI mentah, tetapi dikelola sebagai sumber daya proyek.
apidog schema --help
apidog schema create --project <PROJECT_ID>
Karena keluarannya adalah JSON, Anda dapat menyalurkannya melalui jq untuk mengambil ID skema baru dan memasukkannya ke perintah berikutnya. Jika Anda sudah memiliki file OpenAPI, impor saja daripada mengetik ulang semuanya:
apidog import --project <PROJECT_ID> --file openapi.yaml
apidog import menerima format OpenAPI 3.x, Swagger 2.0, Postman, dan Apidog, sehingga definisi yang ada menjadi proyek langsung dalam satu langkah.
Definisikan endpoint dengan apidog endpoint
Dengan model yang sudah ada, Anda menambahkan operasi. Grup endpoint membuat dan memperbarui endpoint, menghubungkannya ke skema yang Anda definisikan dan ke folder yang mengaturnya.
apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Mendaftar endpoint sebagai JSON sangat berguna. Anda dapat membedakan keluarannya di berbagai cabang atau memasukkannya ke skrip yang memeriksa setiap jalur memiliki respons yang Anda harapkan. Kelompokkan endpoint terkait dengan perintah folder agar proyek tetap mudah dinavigasi seiring pertumbuhannya.
Definisikan autentikasi dengan apidog security-scheme
Autentikasi adalah bagian dari kontrak, bukan sekadar pelengkap. Grup security-scheme mendefinisikan bagaimana klien melakukan autentikasi: kunci API, token bearer, OAuth 2.0, dan sebagainya. Ini memetakan ke components/securitySchemes di OpenAPI, sehingga impor dan ekspor berjalan dengan lancar.
apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Mendefinisikan skema sekali di tingkat proyek berarti setiap endpoint dapat mereferensikannya, daripada setiap operasi mendeklarasikan otentikasinya sendiri. Itulah jenis konsistensi yang akan dipermasalahkan oleh linter.
Validasi penulisan Anda dengan apidog cli-schema validate
Sebelum Anda melakukan perubahan atau menyerahkan proyek ke CI, Anda ingin memastikan definisi sumber daya Anda terbentuk dengan baik. CLI dilengkapi dengan perintah cli-schema validate yang memeriksa file definisi terhadap skema yang diharapkan CLI, sehingga penulisan yang salah bentuk akan gagal dengan cepat daripada masuk secara diam-diam.
apidog cli-schema --help
apidog cli-schema validate --file resource.json
Jalankan ini sebagai langkah pengaman dalam pipeline Anda: validasi terlebih dahulu, lalu terapkan. Keluar dengan nilai bukan nol akan menghentikan pipeline sebelum sumber daya yang buruk mencapai proyek. Ini adalah validasi penulisan CLI Anda, bukan linting gaya OpenAPI; itu adalah dua pekerjaan yang berbeda, dan Anda tetap menginginkan Spectral untuk yang kedua.
Ekspor kembali ke OpenAPI
Desain di Apidog, lalu serahkan artefak standar ke sisa toolchain Anda. apidog export menulis OpenAPI, HTML, Markdown, atau Postman.
apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml
Sekarang Anda kembali ke file OpenAPI yang portabel. Masukkan ke Spectral untuk linting, ke openapi-generator untuk stub, atau ke pembangunan dokumen Anda. Proyek terintegrasi dan tumpukan alat terbuka tidak saling eksklusif; ekspor adalah jembatan di antara keduanya.
Menghubungkannya ke CI
Kedua rute bersinar dalam pipeline karena setiap perintah memiliki kode keluar dan output teks. Pekerjaan pemeriksaan desain minimal mungkin menjalankan linter, kemudian memvalidasi, lalu menggabungkan:
# fail on style violations
spectral lint openapi.yaml
# validate any CLI resource writes before applying
apidog cli-schema validate --file resource.json
# flatten to a single artifact for downstream steps
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Karena output Apidog adalah JSON dengan agentHints.nextSteps, alur ini juga dapat digerakkan dengan lancar dari agen pengkodean AI. Agen membaca hasil terstruktur, melihat langkah selanjutnya yang disarankan, dan menjalankannya, tanpa screen-scraping GUI. Itulah seluruh alasan untuk mendesain dari CLI: apa yang diketik manusia, skrip atau agen juga bisa mengetiknya.
Masalah umum
File terpisah merusak alat hilir. Definisi yang tersebar di banyak file $ref bagus untuk manusia tetapi canggung untuk generator. Selalu gabungkan menjadi satu file sebelum Anda membuat kode atau mempublikasikan dokumen. redocly bundle adalah solusinya.
Anda berharap Apidog melakukan lint. Ia tidak akan. Apidog mengelola sumber daya; ia tidak menegakkan pedoman gaya atau menandai pelanggaran aturan OpenAPI. Pertahankan Spectral atau vacuum dalam alur untuk itu. Menganggap apidog cli-schema validate sebagai linter adalah kesalahpahaman umum; ia memvalidasi struktur sumber daya, bukan gaya OpenAPI.
Lupa mengimpor sebelum mengedit. Jika Anda mengedit API yang sudah ada melalui CLI, impor definisi sumber ke proyek terlebih dahulu. Mengedit proyek kosong dan mengharapkan endpoint lama Anda ada di sana adalah cara cepat untuk menjadi bingung.
Otentikasi didefinisikan per endpoint, bukan sekali. Definisikan security-scheme pada tingkat proyek dan referensikan. Mendeklarasikan ulang otentikasi pada setiap operasi adalah bagaimana kontrak melenceng.
Kesimpulan
Mendesain API dari CLI mengubah tugas yang banyak klik menjadi serangkaian perintah yang dapat diulang. Rute terbuka, membuat, melinting dengan Spectral, menggabungkan dengan Redocly, menghasilkan dengan openapi-generator, memberi Anda kontrol penuh dan tanpa ketergantungan. Rute Apidog CLI memberi Anda proyek terintegrasi di mana skema, endpoint, dan otentikasi hidup bersama dan setiap perintah mengembalikan JSON yang siap untuk agen. Ekspor menjembatani keduanya, sehingga Anda tidak akan pernah terjebak.
Pilih rute yang sesuai dengan tim Anda. Jika Anda sudah terbiasa dengan Git dengan tumpukan alat khusus, pertahankan mereka dan tambahkan apidog export ketika Anda menginginkan artefak portabel. Jika Anda lebih suka tidak memelihara perekat, Unduh Apidog, instal CLI, dan desain API berikutnya tanpa menyentuh mouse.