OpenAPI Generator adalah alat sumber terbuka yang mengubah spesifikasi OpenAPI atau Swagger menjadi kode yang berfungsi: SDK klien, stub server, dan file konfigurasi. Anda menginstal CLI-nya, mengarahkannya ke spesifikasi Anda, memilih generator seperti `typescript-axios` atau `spring`, dan itu menulis kode ke dalam folder keluaran. Panduan ini menunjukkan cara menginstalnya, mencantumkan generator yang tersedia, dan menghasilkan klien serta server untuk beberapa bahasa.
Apa Itu OpenAPI Generator
OpenAPI Generator membaca deskripsi API yang dapat dibaca mesin dan mengeluarkan kode sumber darinya. Berikan file `openapi.yaml` (atau JSON) dan itu dapat menghasilkan pustaka klien untuk memanggil API tersebut, stub server yang mengimplementasikannya, ditambah dokumen dan konfigurasi.
Ini mendukung OpenAPI v2 (format Swagger yang lebih lama) dan OpenAPI v3. Proyek ini dikelola oleh organisasi OpenAPITools di GitHub, dengan templat untuk puluhan bahasa dan kerangka kerja.
Perbedaan utama: ini adalah generator kode, bukan generator dokumentasi. Alat dokumen seperti Swagger UI atau Redoc merender spesifikasi Anda menjadi halaman HTML yang dapat dibaca manusia. OpenAPI Generator justru menghasilkan kode yang Anda kompilasi dan distribusikan. Ini juga dapat mengeluarkan dokumen Markdown, tetapi tugas utamanya adalah SDK dan stub.
Bagaimana Hubungannya dengan Swagger Codegen
Jika Anda pernah menggunakan Swagger Codegen, OpenAPI Generator akan terasa familiar. Ini di-fork dari Swagger Codegen pada Mei 2018, antara versi Swagger Codegen 2.3.1 dan 2.4.0, oleh lebih dari 40 kontributor teratas dan pembuat templatnya.
Fork terjadi setelah ketidaksepakatan mengenai arah Swagger Codegen 3.0.0. Komunitas menginginkan siklus rilis yang lebih cepat dan lebih terbuka. Catatan fork resmi menggambarkan proyek tersebut sebagai berdasarkan Swagger Codegen 2.4.0-SNAPSHOT, jadi keduanya memiliki akar yang dalam. Jika Anda menimbang keduanya, perincian alternatif Swagger Codegen mencakup perbedaan-perbedaan praktisnya.
Menginstal OpenAPI Generator
Anda memiliki empat jalur instalasi umum. Pilih yang sesuai dengan tumpukan Anda.
npm (paling umum)
Pembungkus npm adalah titik masuk termudah untuk sebagian besar tim. Ini mengunduh dan mengelola JAR yang mendasarinya untuk Anda.
npm install @openapitools/openapi-generator-cli -g
Anda juga dapat menjalankannya tanpa instalasi global:
npx @openapitools/openapi-generator-cli version
Homebrew (macOS)
brew install openapi-generator
JAR Mandiri
OpenAPI Generator adalah aplikasi Java, jadi Anda dapat mengunduh JAR langsung dari Maven Central dan menjalankannya dengan Java. Ini sepenuhnya menghindari lapisan npm atau Homebrew.
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
Periksa Maven Central untuk nomor versi terbaru sebelum mengunduh.
Docker
Gambar resmi memungkinkan Anda menghasilkan kode tanpa menginstal apa pun secara lokal. Pasang direktori kerja Anda ke dalam kontainer agar dapat membaca spesifikasi Anda dan menulis keluarannya kembali.
docker pull openapitools/openapi-generator-cli
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi.yaml -g go -o /local/out/go
Mencantumkan generator yang tersedia
Sebelum Anda menghasilkan apa pun, lihat generator apa yang ada. Setiap generator menargetkan bahasa ditambah kerangka kerja, seperti `java`, `python`, atau `spring`.
openapi-generator-cli list
Untuk tampilan ringkas, satu per baris, gunakan flag singkat dan pisahkan pada koma:
openapi-generator-cli list -s | tr ',' '\n'
Daftar tersebut memisahkan generator klien (untuk memanggil API) dari generator server (untuk mengimplementasikan API), ditambah generator dokumentasi dan skema.
Menghasilkan SDK klien
Perintah inti adalah `generate`. Ini membutuhkan tiga argumen yang akan Anda gunakan setiap saat:
-i, --input-specmenunjuk ke file atau URL spesifikasi Anda.-g, --generator-namememilih generator mana yang akan dijalankan.-o, --outputmengatur direktori keluaran.
Berikut adalah klien TypeScript yang dibangun di atas Axios:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Itu menulis klien bertipe ke dalam `./client`. Setiap operasi dalam spesifikasi Anda menjadi sebuah metode, dan setiap skema menjadi sebuah model.
Pola yang sama berfungsi di seluruh bahasa. Tukar nama generator dan folder keluaran:
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
Karena kode berasal dari satu spesifikasi, setiap klien tetap konsisten dengan kontrak. Ketika spesifikasi berubah, Anda meregenerasi dan SDK Anda mengikutinya.
Menghasilkan stub server
Generator server membalik arah. Alih-alih kode yang memanggil API Anda, Anda mendapatkan kerangka kerja yang mengimplementasikannya, dengan perutean, model permintaan, dan antarmuka penangan yang terhubung. Anda mengisi logika bisnis.
Berikut adalah stub server Spring Boot:
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
Proyek yang dihasilkan memberi Anda kontroler dan DTO yang sesuai dengan spesifikasi Anda. Anda mengimplementasikan metode antarmuka, dan bentuk permintaan serta respons sudah ditentukan untuk Anda. Ini menjaga server yang berjalan selaras dengan kontrak yang dipublikasikan.
Mengkonfigurasi keluaran
Keluaran default jarang persis seperti yang Anda inginkan. OpenAPI Generator memberi Anda beberapa kontrol.
Properti tambahan
Sebagian besar generator mengekspos opsi per-bahasa melalui --additional-properties (alias singkat -p). Teruskan sebagai pasangan key=value yang dipisahkan koma:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Setiap generator mendokumentasikan propertinya sendiri, jadi periksa halaman generator untuk daftar lengkap kunci yang diterimanya.
File konfigurasi
Ketika baris perintah menjadi panjang, pindahkan opsi ke dalam file konfigurasi. Baik JSON maupun YAML didukung.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
File konfigurasi menyimpan pengaturan generasi Anda dalam kontrol versi di samping spesifikasi, yang membuat pembangunan dapat direproduksi.
Mengabaikan file
OpenAPI Generator membaca file .openapi-generator-ignore di direktori keluaran. Ini menggunakan sintaks yang sama dengan .gitignore. Gunakan ini untuk menghentikan generator menimpa file yang Anda edit secara manual.
# .openapi-generator-ignore
*.md
src/custom/**
Anda dapat menunjuk ke file abaikan di lokasi lain dengan --ignore-file-override <location>.
Templat kustom
Setiap generator digerakkan oleh templat Mustache. Jika keluaran default tidak sesuai dengan gaya rumah Anda, salin templat, edit, dan teruskan direktori Anda dengan -t:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
Ini adalah alat yang tepat ketika Anda membutuhkan header kustom, klien HTTP yang berbeda, atau konvensi penamaan internal yang sudah terpasang di setiap file yang dihasilkan.
Menjalankannya di CI
Generasi kode termasuk dalam pipeline Anda, bukan di laptop satu pengembang. Regenerasi klien pada setiap perubahan spesifikasi sehingga SDK yang dikomit tidak pernah menyimpang dari kontrak. Berikut adalah langkah GitHub Actions menggunakan `npx`:
- name: Generate API client
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Anda dapat menggagalkan pembangunan jika keluaran yang diregenerasi berbeda dari yang dikomit, yang menangkap spesifikasi dan SDK yang tidak sinkron.
Jadikan spesifikasi sebagai sumber kebenaran tunggal Anda
OpenAPI Generator hanya sebaik spesifikasi yang Anda berikan. Masukan sampah, keluaran sampah: spesifikasi yang samar atau tidak valid menghasilkan SDK yang samar atau rusak. Jadi langkah paling berharga terjadi sebelum Anda menjalankan `generate`. Anda membuat spesifikasi benar, lengkap, dan stabil.
Di sinilah Apidog cocok. Apidog adalah platform API all-in-one yang mendukung OpenAPI secara native, sehingga pekerjaan desain Anda dan spesifikasi Anda adalah artefak yang sama. Anda mendesain atau mengimpor API, dan Apidog menyimpan dokumen OpenAPI sebagai sumber kebenaran dari mana semuanya mengalir.
Alur kerja yang bersih terlihat seperti ini:
- Desain atau impor spesifikasi OpenAPI di Apidog. Dukungan cabang memungkinkan Anda mengerjakan perubahan secara terpisah, mirip dengan mengontrol versi OpenAPI dengan Git.
- Validasi dan lint spesifikasi sebelum Anda menghasilkan. Spesifikasi yang lulus linter OpenAPI dan validator Swagger menghasilkan kode yang lebih bersih dengan lebih sedikit kejutan.
- Ekspor spesifikasi yang divalidasi, lalu berikan ke OpenAPI Generator untuk SDK dan stub Anda.
Anda juga dapat menjaga spesifikasi tetap sinkron dengan repositori Anda, misalnya dengan menyinkronkan spesifikasi OpenAPI ke GitHub, dan meninjau perubahan dengan diff OpenAPI sebelum dikirim. Jika Anda beralih dari alat lama, perbandingan alternatif Swagger untuk desain dan pengujian API adalah titik awal yang baik.
Di mana Apidog Berhenti dan OpenAPI Generator Dimulai
Penting untuk bersikap tepat di sini. Apidog tidak menghasilkan SDK klien lengkap atau stub server. Itu adalah tugas OpenAPI Generator, dan keduanya saling melengkapi daripada bersaing.
Apidog memang memberi Anda cuplikan permintaan klien yang siap disalin untuk setiap titik akhir, dalam banyak bahasa dan klien HTTP. Itu adalah contoh per permintaan yang dapat Anda tempelkan ke skrip, bukan SDK yang dikemas. Untuk pustaka yang dihasilkan dan diberi versi atau kerangka server, Anda menjalankan OpenAPI Generator pada spesifikasi yang dihasilkan Apidog.
Apidog juga menyediakan runner uji baris perintahnya sendiri, Apidog CLI, yang terpisah dari generasi kode. Ini menjalankan pengujian API Anda di CI; itu tidak menghasilkan SDK. Instal dan gunakan seperti ini:
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
Anda meneruskan otentikasi dengan --access-token, -t memilih skenario pengujian, -e memilih lingkungan untuk dijalankan, dan -r memilih pelapor. Jalankan pada rilis Node.js LTS saat ini. Untuk detail pengaturan, lihat panduan instalasi Apidog CLI dan panduan di menguji REST API dari baris perintah.
Jadi alur lengkapnya adalah: desain dan validasi spesifikasi di Apidog, hasilkan SDK dan stub dengan OpenAPI Generator, lalu verifikasi API yang berjalan dengan Apidog CLI.
Coba Apidog gratis, tanpa kartu kredit.
Pertanyaan yang Sering Diajukan
Apa itu OpenAPI Generator?
OpenAPI Generator adalah alat sumber terbuka dari organisasi OpenAPITools yang menghasilkan kode dari spesifikasi OpenAPI atau Swagger. Ini menghasilkan SDK klien, stub server, dokumentasi, dan file konfigurasi, dan mendukung OpenAPI v2 dan v3.
Bagaimana cara menggunakan OpenAPI Generator?
Instal CLI (misalnya npm install @openapitools/openapi-generator-cli -g), lalu jalankan generate dengan tiga flag: -i untuk spesifikasi Anda, -g untuk generator, dan -o untuk folder keluaran. Jalankan openapi-generator-cli list terlebih dahulu untuk melihat setiap generator yang tersedia.
Bagaimana cara kerja OpenAPI Generator?
Ini mengurai spesifikasi Anda menjadi model internal, lalu merender model itu melalui templat Mustache untuk target pilihan Anda. Setiap operasi menjadi metode atau penangan, dan setiap skema menjadi model bertipe. Anda dapat menimpa templat dengan -t untuk mengubah keluaran.
Bagaimana cara menghasilkan SDK klien dari spesifikasi OpenAPI?
Pilih generator klien dan jalankan generate. Misalnya, openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client membangun klien TypeScript bertipe. Tukar typescript-axios dengan java, python, atau go untuk menargetkan bahasa lain.
Bagaimana cara menghasilkan stub server?
Pilih generator server. Untuk kerangka Spring Boot, jalankan openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring. Keluaran mencakup kontroler dan model permintaan dari spesifikasi Anda, dan Anda mengimplementasikan logika penangan.
Apa perbedaan antara OpenAPI Generator dan Swagger Codegen?
OpenAPI Generator di-fork dari Swagger Codegen pada Mei 2018 oleh lebih dari 40 kontributornya, yang menginginkan siklus rilis yang lebih cepat dan didorong oleh komunitas. Keduanya memiliki dasar yang sama, tetapi OpenAPI Generator sekarang memiliki peta jalan, set generator, dan jadwal rilisnya sendiri.
Bagaimana cara menghasilkan PHP SDK dari spesifikasi OpenAPI?
Gunakan generator php: openapi-generator-cli generate -i openapi.yaml -g php -o ./client-php. Jalankan openapi-generator-cli list untuk mengkonfirmasi nama generator yang tepat dan untuk melihat opsi kerangka kerja PHP lainnya sebelum Anda menghasilkan.