Swagger UI adalah alat yang memungkinkan Anda untuk melihat dokumentasi API yang dihasilkan dalam spesifikasi Swagger (Spesifikasi OpenAPI). Swagger UI juga menyediakan versi offline dan online untuk Anda, tetapi karena berbagai alasan, Anda mungkin perlu membuka file spesifikasi Swagger yang dihasilkan dengan Swagger UI secara lokal. Dalam artikel ini, kami akan menunjukkan cara menjalankan Swagger UI secara lokal, jika Anda mengalami beberapa masalah dalam proses ini, ikuti terus.
Apa itu Swagger UI?
Swagger UI adalah alat yang memungkinkan Anda untuk menampilkan dan memverifikasi definisi API yang ditulis dalam Spesifikasi OpenAPI (sebelumnya Spesifikasi Swagger) secara interaktif. Dengan menyiapkan Swagger UI di lingkungan lokal dan mengimpor definisi API, pengembang dapat mengembangkan sambil memeriksa spesifikasi API secara real time.
Mengapa menggunakan Swagger UI secara lokal?
Meskipun Swagger UI menawarkan versi SaaS, banyak pengguna lebih suka menginstalnya di mesin lokal mereka dan menyiapkan server web lokal. Akibatnya, banyak pengguna mengakses Swagger UI di localhost mereka. Jadi, apa keuntungan menggunakan Swagger UI secara lokal? Mari kita jelajahi manfaat ini secara detail.
Alasan utama untuk memanfaatkan Swagger UI di lingkungan lokal meliputi:
- Pengembangan API Real-Time: Saat mengembangkan API secara lokal, penting untuk memiliki kemampuan untuk memeriksa definisi API secara real time.
- Referensi Dokumentasi Offline: Penggunaan lokal memungkinkan Anda untuk mereferensikan dokumentasi API secara offline, menghilangkan kebutuhan akan koneksi jaringan.
- Privasi yang Ditingkatkan: Penggunaan lokal memastikan bahwa API Anda yang sedang dalam pengembangan tetap pribadi, tanpa perlu publikasi eksternal, menjauhkannya dari akses pihak ketiga.
- Pengujian Mock Server: Anda dapat menyiapkan dan menguji Mock server lokal untuk memverifikasi fungsionalitas API Anda.
- Definisi API Iteratif: Penggunaan lokal memungkinkan Anda untuk membuat perubahan iteratif pada definisi API dan memeriksa dampaknya setiap kali.
- Validasi Pipeline CI/CD: Validasi lokal menjadi bagian dari pipeline CI/CD Anda, memastikan keandalan dan kualitas API Anda selama pengembangan.
Keuntungan menggunakan Swagger UI secara lokal
Keuntungan menggunakan Swagger UI di lingkungan lokal tercantum di bawah ini, tetapi yang terbaik adalah memutuskan apakah akan menggunakan layanan berbasis cloud atau menggunakannya secara lokal tergantung pada situasi spesifik.
- Dapat digunakan secara offline karena tidak bergantung pada lingkungan internet
- Pengembangan mudah karena Anda dapat memeriksa definisi API lokal secara real time
- Tidak perlu mengekspos API yang sedang dikembangkan ke dunia luar.
- Anda dapat menyiapkan mock server secara lokal, sehingga Anda dapat memeriksa operasinya.
- Responsnya cepat karena tidak bergantung pada spesifikasi mesin pengembangan.
- Tingkatkan produktivitas dengan mengembangkan sesuai kecepatan Anda sendiri
- Lebih aman daripada menggunakan server bersama
- Mudah untuk menyinkronkan definisi dan implementasi API
Bagaimana Cara Menggunakan Swagger UI Secara Lokal?
Jadi, apa yang harus saya lakukan jika saya ingin menggunakan Swagger UI secara lokal? Selanjutnya, saya akan menjelaskan secara detail cara menggunakan Swagger UI secara lokal.
Instal Swagger UI dan siapkan lingkungan Dev
Pertama, Anda perlu mengunduh Swagger UI dan menginstalnya di mesin lokal Anda. Versi terbaru lebih disukai. Repositori Swagger UI dikelola di GitHub, jadi silakan instal menggunakan perintah berikut.
git clone https://github.com/swagger-api/swagger-ui.git
Kemudian siapkan lingkungan Dev Anda menggunakan perintah seperti:
cd swagger-ui
npm run dev
Swagger UI akan diluncurkan dengan mengakses http://localhost:3200/ di browser Anda.
Siapkan server web lokal
Selanjutnya, untuk meluncurkan Swagger UI, Anda perlu menyiapkan server web menggunakan baris perintah berikut. Di sini kita akan menggunakan modul http-server Node.js.
npm install -g http-server
Mulai HTTP-server dan luncurkan Swagger UI
Navigasi ke direktori tempat file Spesifikasi Swagger berada, mulai http-server di direktori itu, dan aktifkan CORS menggunakan perintah seperti berikut:
cd {your-oas-document-dir}
http-server --cors
Kemudian, http://localhost``:8080ketika Anda mengaksesnya di browser Anda, Swagger UI akan diluncurkan.
Siapkan file spesifikasi Swagger
Selanjutnya, siapkan file Spesifikasi Swagger. Umumnya, file spesifikasi Swagger ditulis dalam format Json atau Yaml. Misalnya, swagger.yaml misalkan Anda menuliskannya dalam sebuah file bernama. URL file spec Swagger adalah http://localhost:8080/swagger.yaml.
Juga, jika Anda ingin tahu lebih banyak tentang file Spec Swagger atau mengubah jalur default URL Swagger UI, silakan merujuk ke artikel berikut:
Masukkan URL file spesifikasi Swagger dan buka di Swagger UI
Kemudian, pada layar Swagger UI, masukkan URL swagger.yaml di URL SPEC di atas di kotak input di bagian atas, dan klik tombol Explore untuk menampilkan dokumen definisi API lokal.
Apidog: Kelola API Anda dengan lebih efisien
Saat menggunakan Swagger UI, Anda perlu membangun server dan mengatur URL, yang bisa sangat merepotkan. Jika Anda mencari solusi yang lebih mudah, kami sarankan untuk menggunakan Apidog, alat manajemen API yang mudah digunakan.
Apidog dapat membaca file Swagger Json dan Yaml secara langsung dan dengan cepat menguji API Anda. Anda juga dapat menggunakan fitur berbagi untuk menghasilkan dan berbagi dokumentasi API yang indah.
Impor JSON dan YAML dengan mudah ke Apidog
Apidog mendukung pengimporan data dengan YAML dan JSON, sehingga Anda dapat sepenuhnya mengurai file-file ini dan sepenuhnya mengimpor data API Anda ke Apidog untuk pengujian.
Buka pengaturan proyek Anda di Apidog, klik Impor Data, pilih OpenAPI/Swagger, dan seret file YAML ke Apidog.
Uji API Anda dengan Apidog
Setelah Anda mengimpor data API Anda ke Apidog, Anda dapat melihat API yang diimpor dengan mengklik tab API di sebelah kiri. Jika Anda ingin menguji endpoint API tertentu, Anda dapat mengkliknya, mengisi parameter dalam UI yang intuitif, "kirim" permintaan, dan dapatkan respons.
Menghasilkan dan berbagi dokumentasi API juga sangat mudah menggunakan Apidog. Berikut ini adalah contoh dokumentasi API yang dihasilkan oleh Apidog:
FAQ tentang Swagger UI Localhost
Bagaimana cara mengakses Swagger UI di localhost?
- Jalankan proyek API Anda secara lokal, lalu navigasikan ke
http://localhost``:<port>/swaggerdi browser Anda. Port biasanya 5000 atau 5001.
Apa URL untuk Swagger local host?
- URL default adalah http://localhost:/swagger di mana port API Anda berjalan secara lokal.
Bagaimana cara menghosting dokumentasi Swagger secara lokal?
- Aktifkan Swagger dalam kode startup Anda, luncurkan proyek API, dan navigasikan ke endpoint /swagger untuk melihat UI.
Apa URL Swagger untuk localhost .NET core?
- Untuk API .NET Core, URL Swagger biasanya http://localhost:/swagger/v1/swagger.json
Ringkasan
Swagger UI adalah alat yang berguna saat mengembangkan API, tetapi memiliki keterbatasan untuk manajemen siklus hidup API yang lebih canggih. Apidog menyediakan fungsionalitas satu atap untuk pengembangan API, seperti definisi API, pembuatan dokumen otomatis, pengujian, pemantauan, dan berbagi.
Apidog memungkinkan Anda untuk mengimpor file spesifikasi Swagger dan OpenAPI dan menguji API Anda secara interaktif. Fitur berbagi memungkinkan Anda untuk membuat dokumen yang indah dan membaginya dengan tim Anda. Jika Anda ingin menyederhanakan proses pengembangan API Anda, Apidog adalah solusi untuk Anda. Dengan menggunakannya bersama dengan Swagger UI, Anda akan dapat mencapai manajemen siklus hidup API yang lebih kuat.
