DEV Community

Cover image for Cara Mendesain API dari CLI
Walse
Walse

Posted on • Originally published at apidog.com

Cara Mendesain API dari CLI

Sebagian besar tutorial desain API dimulai dari editor visual. Namun, jika definisi API Anda disimpan di Git, ditinjau melalui pull request, dan divalidasi di CI, workflow berbasis terminal lebih mudah diulang dan diotomatisasi. Anda dapat membuat kontrak API, memvalidasinya, menggabungkan file, dan menghasilkan stub server tanpa meninggalkan shell.

Coba Apidog hari ini

Pendekatan ini membuat setiap langkah eksplisit dan dapat diskrip. Rekan tim, CI, atau agen AI cukup menjalankan perintah yang sama untuk mereproduksi hasilnya.

Artikel ini membahas dua rute:

  1. Toolchain open-source: OpenAPI + Spectral + Redocly CLI + openapi-generator.
  2. Apidog CLI: mengelola skema, endpoint, dan autentikasi dalam satu proyek dari terminal.

Untuk dasar konseptual, baca panduan cara mendesain API dan mendesain REST API.

Jika menggunakan Apidog, instal CLI dan login terlebih dahulu. Panduan instalasi Apidog CLI menjelaskan npm install -g apidog-cli dan autentikasi dengan apidog login --with-token. Lihat juga panduan Apidog CLI lengkap untuk daftar kelompok perintah.

Rute open-source: buat, lint, gabungkan, hasilkan

Toolchain CLI klasik terdiri dari beberapa alat independen. Simpan spesifikasi OpenAPI di repository, lalu jalankan setiap alat sebagai tahap pipeline. Ini cocok untuk alur kerja desain API Git-native.

1. Buat dokumen OpenAPI

Mulai dari file YAML biasa, misalnya openapi.yaml:

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]
Enter fullscreen mode Exit fullscreen mode

Saat spesifikasi bertambah besar, pisahkan schema, path, dan parameter ke beberapa file menggunakan $ref. Struktur ini memudahkan review karena perubahan model dapat diperiksa secara independen.

Contoh struktur proyek:

api/
├── openapi.yaml
├── paths/
│   └── orders.yaml
└── schemas/
    └── order.yaml
Enter fullscreen mode Exit fullscreen mode

2. Lint dengan Spectral

Spesifikasi yang ditulis manual sering memiliki inkonsistensi: operationId hilang, respons tidak terdokumentasi, atau konvensi penamaan berbeda. Jalankan linter sebelum merge.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Spectral menampilkan pelanggaran beserta nomor baris dan tingkat keparahannya. Di CI, cukup gunakan exit code untuk menggagalkan build ketika ada error.

Alternatifnya adalah Redocly CLI atau vacuum. Vacuum dapat digunakan sebagai linter yang kompatibel dengan Spectral. Apa pun alatnya, jadikan linting sebagai langkah pipeline tersendiri.

3. Gabungkan file dengan Redocly CLI

Tool seperti generator SDK atau publisher dokumentasi biasanya membutuhkan satu file OpenAPI mandiri. Gunakan redocly bundle untuk menyelesaikan semua $ref.

npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Hasil dist/openapi.bundled.yaml dapat digunakan sebagai artefak untuk proses berikutnya.

Redocly juga menyediakan linting melalui redocly lint dan pratinjau dokumentasi. Lihat dokumentasi Redocly CLI untuk perintah lengkap.

4. Hasilkan stub server dengan openapi-generator

Setelah spesifikasi sudah bersih dan tergabung, hasilkan kode awal server atau SDK klien.

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

Ganti generator sesuai stack Anda:

# Python Flask
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g python-flask \
  -o ./server

# Go server
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g go-server \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

Rute ini memberi kontrol penuh: Anda memilih struktur file, aturan lint, format bundle, dan generator. Konsekuensinya, Anda perlu memelihara konfigurasi serta integrasi antaralat sendiri.

Rute Apidog CLI: desain dalam satu proyek

Alternatifnya adalah menyimpan skema, endpoint, autentikasi, mock, dan struktur folder dalam satu proyek yang dikelola melalui apidog-cli.

CLI ini menyediakan kelompok perintah untuk sumber daya API:

  • schema untuk model data
  • endpoint untuk operasi API
  • folder untuk organisasi endpoint
  • security-scheme untuk autentikasi
  • import dan export untuk pertukaran format
  • mock dan perintah proyek lainnya

Satu batasan penting: Apidog tidak berfungsi sebagai linter OpenAPI atau penegak style guide. Jika Anda memerlukan linting, tetap jalankan Spectral atau vacuum dalam pipeline. Apidog adalah produk komersial dengan tingkatan gratis, tetapi dapat mengurangi kebutuhan untuk merangkai sendiri berbagai bagian desain. Lihat alternatif Swagger untuk desain dan pengujian API untuk konteks pertukarannya.

1. Instal dan autentikasi 

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Setiap perintah mengembalikan JSON terstruktur. Sebagian besar respons juga menyertakan agentHints.nextSteps, sehingga skrip atau agen dapat membaca hasilnya dan menentukan langkah berikutnya. Tambahkan --help pada perintah apa pun untuk melihat flag yang tersedia.

2. Definisikan model data dengan apidog schema

Model data yang dapat digunakan kembali sebaiknya menjadi sumber kebenaran tunggal. Konsepnya setara dengan components/schemas di OpenAPI.

apidog schema --help
apidog schema create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Karena output CLI berbentuk JSON, gunakan jq jika Anda perlu mengambil ID sumber daya untuk perintah berikutnya.

apidog schema create --project <PROJECT_ID> | jq -r '.data.id'
Enter fullscreen mode Exit fullscreen mode

Jika sudah memiliki spesifikasi OpenAPI, impor langsung agar tidak perlu membuat ulang semua schema dan endpoint:

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

apidog import mendukung OpenAPI 3.x, Swagger 2.0, Postman, dan format Apidog.

3. Definisikan endpoint dengan apidog endpoint

Gunakan grup endpoint untuk membuat, memperbarui, dan memeriksa operasi API.

apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Output JSON dari endpoint list berguna untuk otomatisasi. Contohnya, Anda dapat menyimpan output per branch lalu membandingkannya untuk mendeteksi endpoint yang berubah atau hilang.

Kelompokkan endpoint terkait menggunakan perintah folder agar proyek tetap mudah dinavigasi saat jumlah endpoint bertambah.

4. Definisikan autentikasi dengan apidog security-scheme

Autentikasi adalah bagian dari kontrak API. Definisikan skema autentikasi sekali di tingkat proyek, lalu referensikan dari endpoint yang membutuhkannya.

apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Kelompok ini mencakup mekanisme seperti API key, bearer token, dan OAuth 2.0. Konsepnya dipetakan ke components/securitySchemes pada OpenAPI, sehingga proses impor dan ekspor tetap selaras.

5. Validasi file sumber daya dengan cli-schema validate

Sebelum menerapkan perubahan dari file definisi, validasi struktur file tersebut.

apidog cli-schema --help
apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

Tambahkan langkah ini ke CI sebelum perubahan diterapkan:

apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

Perintah ini memvalidasi bentuk file sumber daya yang diharapkan CLI. Ini bukan pengganti linting OpenAPI: gunakan Spectral atau vacuum untuk memeriksa style guide dan aturan OpenAPI.

6. Ekspor kembali ke OpenAPI

Setelah mendesain API dalam proyek Apidog, ekspor artefak standar untuk toolchain lain.

apidog export \
  --project <PROJECT_ID> \
  --format openapi \
  -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Gunakan hasil ekspor untuk linting, code generation, atau publikasi dokumentasi:

spectral lint dist/openapi.yaml

openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

Dengan begitu, proyek Apidog dan toolchain open-source dapat digunakan bersama. Ekspor OpenAPI menjadi jembatan di antara keduanya.

Hubungkan ke CI

Kedua rute cocok untuk CI karena berbasis perintah, output teks, dan exit code. Pipeline minimal dapat terlihat seperti ini:

# Gagal jika ada pelanggaran style OpenAPI.
spectral lint openapi.yaml

# Validasi file sumber daya CLI sebelum diterapkan.
apidog cli-schema validate --file resource.json

# Buat satu artefak OpenAPI untuk generator dan dokumentasi.
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

# Opsional: hasilkan stub server.
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

Contoh GitHub Actions sederhana:

name: Validate API

on:
  pull_request:
    paths:
      - "api/**"
      - "resource.json"

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install CLI tools
        run: |
          npm install -g @stoplight/spectral-cli
          npm install -g @redocly/cli

      - name: Lint OpenAPI
        run: spectral lint api/openapi.yaml

      - name: Bundle OpenAPI
        run: redocly bundle api/openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Output JSON dari Apidog, termasuk agentHints.nextSteps, juga memungkinkan workflow ini dijalankan oleh agen pengkodean tanpa bergantung pada GUI.

Masalah umum

File terpisah merusak tool hilir.

Struktur $ref yang terpisah nyaman untuk manusia, tetapi generator dan publisher dokumentasi sering membutuhkan satu file. Jalankan redocly bundle sebelum code generation atau deployment dokumentasi.

Menganggap Apidog sebagai linter.

Apidog mengelola sumber daya proyek, bukan aturan gaya OpenAPI. Gunakan Spectral atau vacuum untuk linting. apidog cli-schema validate hanya memvalidasi struktur file sumber daya CLI.

Mengedit proyek kosong tanpa impor.

Jika API sudah ada dalam OpenAPI atau Swagger, impor dulu ke proyek:

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Jangan mengharapkan endpoint lama tersedia dalam proyek baru yang belum diimpor.

Mendefinisikan autentikasi berulang per endpoint.

Buat security-scheme pada tingkat proyek dan gunakan ulang. Pendekatan ini menjaga kontrak autentikasi tetap konsisten di seluruh operasi.

Kesimpulan

Desain API dari CLI mengubah proses berbasis klik menjadi rangkaian perintah yang dapat diulang, direview, dan dijalankan di CI.

Gunakan rute open-source jika Anda menginginkan kontrol penuh:

  1. Tulis OpenAPI.
  2. Lint dengan Spectral.
  3. Bundle dengan Redocly.
  4. Generate kode dengan openapi-generator.

Gunakan Apidog CLI jika Anda ingin mengelola skema, endpoint, dan autentikasi sebagai satu proyek terintegrasi, lalu ekspor OpenAPI saat dibutuhkan.

Pilih berdasarkan workflow tim Anda. Jika Anda sudah memiliki toolchain Git-native, pertahankan dan tambahkan apidog export saat memerlukan artefak portabel. Jika ingin mengurangi konfigurasi perekat antaralat, unduh Apidog, instal CLI, dan desain API berikutnya langsung dari terminal.

Top comments (0)