DEV Community

Cover image for OpenAPI Generator: Cara Menghasilkan Kode Klien dan Server API
Walse
Walse

Posted on • Originally published at apidog.com

OpenAPI Generator: Cara Menghasilkan Kode Klien dan Server API

OpenAPI Generator adalah alat sumber terbuka untuk mengubah spesifikasi OpenAPI atau Swagger menjadi kode siap pakai: SDK klien, stub server, dokumentasi, dan file konfigurasi. Alur dasarnya: instal CLI, arahkan ke openapi.yaml, pilih generator seperti typescript-axios atau spring, lalu tulis hasilnya ke folder keluaran.

Coba Apidog hari ini

Apa Itu OpenAPI Generator

OpenAPI Generator membaca kontrak API yang dapat diproses mesin, lalu menghasilkan kode dari kontrak tersebut. Input-nya bisa berupa file openapi.yaml, openapi.json, atau URL spesifikasi.

Output yang umum:

  • SDK klien untuk memanggil API.
  • Stub server untuk mengimplementasikan API.
  • Model request/response.
  • Dokumentasi dan konfigurasi proyek.

OpenAPI Generator mendukung OpenAPI v2 atau Swagger lama dan OpenAPI v3. Proyek ini dikelola oleh organisasi OpenAPITools di GitHub dan menyediakan templat untuk banyak bahasa serta framework.

Perlu dibedakan: OpenAPI Generator adalah generator kode, bukan sekadar generator dokumentasi. Swagger UI atau Redoc merender spesifikasi menjadi halaman HTML. OpenAPI Generator menghasilkan kode yang dapat Anda kompilasi, impor, dan distribusikan.

Hubungannya dengan Swagger Codegen

OpenAPI Generator di-fork dari Swagger Codegen pada Mei 2018, di antara versi Swagger Codegen 2.3.1 dan 2.4.0, oleh lebih dari 40 kontributor dan pembuat templatnya.

Fork ini terjadi setelah perbedaan arah terkait Swagger Codegen 3.0.0. Komunitas menginginkan proses rilis yang lebih cepat dan terbuka. Jika Anda sedang membandingkan keduanya, baca pembahasan alternatif Swagger Codegen.

Menginstal OpenAPI Generator

Pilih metode instalasi yang sesuai dengan workflow Anda.

npm

Untuk banyak tim JavaScript/TypeScript, pembungkus npm adalah opsi paling praktis karena mengelola JAR OpenAPI Generator di balik layar.

npm install @openapitools/openapi-generator-cli -g
Enter fullscreen mode Exit fullscreen mode

Cek versi:

openapi-generator-cli version
Enter fullscreen mode Exit fullscreen mode

Atau jalankan tanpa instalasi global:

npx @openapitools/openapi-generator-cli version
Enter fullscreen mode Exit fullscreen mode

Homebrew di macOS 

brew install openapi-generator
Enter fullscreen mode Exit fullscreen mode

JAR mandiri

OpenAPI Generator adalah aplikasi Java. Jika Anda ingin menghindari npm atau Homebrew, jalankan langsung dengan JAR.

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar

java -jar openapi-generator-cli.jar help
Enter fullscreen mode Exit fullscreen mode

Sebelum mengunduh, cek Maven Central untuk versi terbaru.

Docker

Gunakan Docker jika Anda tidak ingin memasang dependency lokal.

docker pull openapitools/openapi-generator-cli
Enter fullscreen mode Exit fullscreen mode

Contoh menjalankan generator Go:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i /local/openapi.yaml \
  -g go \
  -o /local/out/go
Enter fullscreen mode Exit fullscreen mode

Di sini:

  • -v "${PWD}:/local" memasang direktori kerja ke container.
  • -i /local/openapi.yaml menunjuk ke spesifikasi.
  • -o /local/out/go menulis hasil ke folder lokal.

Mencantumkan Generator yang Tersedia

Sebelum menghasilkan kode, lihat daftar generator yang tersedia.

openapi-generator-cli list
Enter fullscreen mode Exit fullscreen mode

Untuk output yang lebih mudah dipindai:

openapi-generator-cli list -s | tr ',' '\n'
Enter fullscreen mode Exit fullscreen mode

Generator biasanya dibagi menjadi:

  • Client generator, misalnya typescript-axios, java, python, go, php.
  • Server generator, misalnya spring.
  • Documentation generator.
  • Schema/config generator.

Menghasilkan SDK Klien

Perintah utama adalah generate.

Format umumnya:

openapi-generator-cli generate \
  -i <input-spec> \
  -g <generator-name> \
  -o <output-dir>
Enter fullscreen mode Exit fullscreen mode

Tiga flag yang paling sering dipakai:

  • -i atau --input-spec: lokasi file atau URL spesifikasi.
  • -g atau --generator-name: nama generator.
  • -o atau --output: folder keluaran.

Contoh: TypeScript + Axios 

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Hasilnya adalah klien TypeScript bertipe di folder ./client.

Biasanya:

  • Setiap endpoint menjadi method.
  • Setiap schema menjadi model.
  • Request dan response mengikuti kontrak OpenAPI.

Contoh: Java, Python, dan Go

Gunakan pola yang sama, lalu ganti generator dan folder output.

openapi-generator-cli generate -i openapi.yaml -g java   -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go     -o ./client-go
Enter fullscreen mode Exit fullscreen mode

Jika spesifikasi berubah, regenerasi SDK agar kode tetap sinkron dengan kontrak API.

Menghasilkan Stub Server

Generator server menghasilkan kerangka implementasi API. Anda mendapatkan routing, model request/response, controller, dan interface handler. Logika bisnis tetap Anda isi sendiri.

Contoh stub server Spring Boot:

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

Output-nya memberi struktur awal seperti:

  • Controller.
  • DTO/model.
  • Interface atau handler method.
  • Kontrak request dan response berdasarkan spesifikasi.

Pendekatan ini berguna jika Anda ingin memulai implementasi server dari kontrak API yang sudah disepakati.

Mengonfigurasi Output

Output default sering belum sesuai dengan standar proyek. OpenAPI Generator menyediakan beberapa cara konfigurasi.

Menggunakan --additional-properties

Sebagian besar generator memiliki opsi spesifik bahasa/framework melalui --additional-properties atau -p.

Contoh untuk typescript-axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  --additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Enter fullscreen mode Exit fullscreen mode

Contoh properti di atas:

  • npmName=@acme/api-client: nama paket npm.
  • supportsES6=true: output mendukung ES6.
  • withSeparateModelsAndApi=true: pisahkan model dan API.

Setiap generator memiliki properti berbeda, jadi cek dokumentasi generator sebelum menetapkan konfigurasi final.

Menggunakan File Konfigurasi

Jika command terlalu panjang, pindahkan opsi ke file konfigurasi.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -c config.yaml
Enter fullscreen mode Exit fullscreen mode

Contoh config.yaml:

npmName: "@acme/api-client"
supportsES6: true
withSeparateModelsAndApi: true
Enter fullscreen mode Exit fullscreen mode

Simpan file konfigurasi di version control bersama spesifikasi agar proses generate mudah diulang di lokal dan CI.

Mengabaikan File Tertentu

OpenAPI Generator membaca .openapi-generator-ignore di folder output. Sintaksnya mirip .gitignore.

Contoh:

# .openapi-generator-ignore
*.md
src/custom/**
Enter fullscreen mode Exit fullscreen mode

Gunakan ini untuk mencegah generator menimpa file yang Anda edit manual.

Anda juga bisa menunjuk file ignore lain:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  --ignore-file-override ./generator-ignore
Enter fullscreen mode Exit fullscreen mode

Menggunakan Template Kustom

OpenAPI Generator memakai template Mustache. Jika output default tidak cocok dengan konvensi tim, gunakan template sendiri.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -t ./my-templates
Enter fullscreen mode Exit fullscreen mode

Template kustom berguna untuk:

  • Header file internal.
  • Konvensi penamaan khusus.
  • Struktur folder yang disesuaikan.
  • HTTP client wrapper yang sudah distandarkan.

Menjalankan OpenAPI Generator di CI

Generasi kode sebaiknya masuk pipeline, bukan hanya dijalankan di laptop satu developer.

Contoh GitHub Actions dengan npx:

- name: Generate API client
  run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Enter fullscreen mode Exit fullscreen mode

Untuk mencegah SDK tertinggal dari spesifikasi, tambahkan pengecekan git diff setelah generate.

- name: Check generated client is up to date
  run: |
    npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
    git diff --exit-code
Enter fullscreen mode Exit fullscreen mode

Jika hasil generate berbeda dari kode yang dikomit, build akan gagal. Ini membantu menangkap perubahan spesifikasi yang belum diikuti regenerasi SDK.

Jadikan Spesifikasi sebagai Sumber Kebenaran Tunggal

OpenAPI Generator hanya sebaik spesifikasi yang Anda berikan. Spesifikasi yang tidak valid, ambigu, atau tidak lengkap akan menghasilkan SDK dan stub yang bermasalah.

Sebelum menjalankan generate, pastikan spesifikasi Anda:

  • Valid secara sintaks.
  • Memiliki schema request/response yang jelas.
  • Konsisten pada penamaan path, operation ID, dan model.
  • Stabil sebelum dibagikan ke konsumen API.

Di sinilah Apidog dapat digunakan. Apidog adalah platform API all-in-one yang mendukung OpenAPI secara native. Anda bisa mendesain atau mengimpor API, lalu menjadikan dokumen OpenAPI sebagai sumber kebenaran.

Workflow yang praktis:

  1. Desain atau impor spesifikasi OpenAPI di Apidog. Dukungan branch membantu mengerjakan perubahan secara terpisah, mirip dengan mengontrol versi OpenAPI dengan Git.
  2. Validasi dan lint spesifikasi sebelum generate. Spesifikasi yang lolos linter OpenAPI dan validator Swagger biasanya menghasilkan kode yang lebih bersih.
  3. Ekspor spesifikasi yang sudah divalidasi.
  4. Jalankan OpenAPI Generator untuk membuat SDK klien atau stub server.
  5. Jalankan pengujian API di CI.

Anda juga dapat menjaga spesifikasi tetap sinkron dengan repository, misalnya dengan menyinkronkan spesifikasi OpenAPI ke GitHub, lalu meninjau perubahan menggunakan diff OpenAPI. Jika Anda beralih dari tool lama, perbandingan alternatif Swagger untuk desain dan pengujian API bisa menjadi titik awal.

Di Mana Apidog Berhenti dan OpenAPI Generator Dimulai

Apidog tidak menghasilkan SDK klien lengkap atau stub server. Itu adalah peran OpenAPI Generator.

Pembagian perannya:

  • Apidog: desain, dokumentasi, validasi, kolaborasi, dan pengujian API.
  • OpenAPI Generator: menghasilkan SDK klien, stub server, model, dan konfigurasi dari spesifikasi OpenAPI.
  • Apidog CLI: menjalankan pengujian API di command line atau CI.

Apidog menyediakan cuplikan request siap salin untuk setiap endpoint dalam banyak bahasa dan HTTP client. Namun, cuplikan tersebut adalah contoh per request, bukan SDK lengkap yang dikemas dan diberi versi.

Untuk SDK atau server framework, jalankan OpenAPI Generator pada spesifikasi yang diekspor dari Apidog.

Menjalankan Pengujian API dengan Apidog CLI

Apidog CLI terpisah dari OpenAPI Generator. Fungsinya menjalankan pengujian API, bukan menghasilkan SDK.

Instal:

npm install -g apidog-cli@latest
Enter fullscreen mode Exit fullscreen mode

Jalankan skenario pengujian:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <testScenarioId> \
  -e <envId> \
  -r cli,html \
  -n 1
Enter fullscreen mode Exit fullscreen mode

Parameter utama:

  • --access-token: token autentikasi.
  • -t: ID skenario pengujian.
  • -e: ID environment.
  • -r: reporter, misalnya cli dan html.
  • -n: jumlah iterasi.

Gunakan rilis Node.js LTS saat ini. Untuk detail, lihat panduan instalasi Apidog CLI dan panduan menguji REST API dari baris perintah.

Alur lengkapnya:

Desain dan validasi spesifikasi di Apidog
        ↓
Ekspor OpenAPI
        ↓
Generate SDK/stub dengan OpenAPI Generator
        ↓
Jalankan pengujian API dengan Apidog CLI
Enter fullscreen mode Exit fullscreen mode

Coba Apidog gratis, tanpa kartu kredit.

Pertanyaan yang Sering Diajukan

Apa itu OpenAPI Generator?

OpenAPI Generator adalah alat sumber terbuka dari organisasi OpenAPITools untuk menghasilkan kode dari spesifikasi OpenAPI atau Swagger. Output-nya dapat berupa SDK klien, stub server, dokumentasi, dan file konfigurasi. OpenAPI Generator mendukung OpenAPI v2 dan v3.

Bagaimana cara menggunakan OpenAPI Generator?

Instal CLI, lalu jalankan generate dengan tiga flag utama:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Gunakan openapi-generator-cli list untuk melihat generator yang tersedia.

Bagaimana cara kerja OpenAPI Generator?

OpenAPI Generator mengurai spesifikasi menjadi model internal, lalu merender model tersebut melalui template Mustache untuk target yang dipilih. Operasi API menjadi method atau handler, sedangkan schema menjadi model bertipe.

Bagaimana cara menghasilkan SDK klien dari spesifikasi OpenAPI?

Pilih generator klien dan jalankan generate.

Contoh TypeScript Axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Untuk bahasa lain, ganti generator:

openapi-generator-cli generate -i openapi.yaml -g java   -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go     -o ./client-go
Enter fullscreen mode Exit fullscreen mode

Bagaimana cara menghasilkan stub server?

Pilih generator server. Untuk Spring Boot:

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

Output-nya mencakup controller dan model berdasarkan spesifikasi. Anda mengisi logika bisnis pada handler yang dihasilkan.

Apa perbedaan OpenAPI Generator dan Swagger Codegen?

OpenAPI Generator di-fork dari Swagger Codegen pada Mei 2018 oleh lebih dari 40 kontributor. Keduanya memiliki dasar yang sama, tetapi OpenAPI Generator memiliki roadmap, daftar generator, dan jadwal rilis sendiri.

Bagaimana cara menghasilkan PHP SDK dari spesifikasi OpenAPI?

Gunakan generator php.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g php \
  -o ./client-php
Enter fullscreen mode Exit fullscreen mode

Jalankan openapi-generator-cli list untuk memastikan nama generator dan melihat opsi PHP lain yang tersedia.

Top comments (0)