Swagger UI adalah alat yang hebat untuk memvisualisasikan dan berinteraksi dengan spesifikasi OpenAPI. Saat Anda bekerja dengan Swagger UI, Anda akan melihat URL memainkan peran penting dalam mengonfigurasi dan mengakses dokumentasi API. Dalam postingan ini, kami akan menguraikan URL Swagger UI untuk membantu Anda menggunakannya dengan lebih efektif.
Apa itu Swagger UI?
Swagger UI adalah alat yang memungkinkan pengguna untuk berinteraksi dengan API menggunakan dokumentasi Spesifikasi OpenAPI. Alat ini membaca dokumen spesifikasi dan menampilkannya dalam format interaktif secara visual. Ini membantu pengembang untuk memahami API, mengirim permintaan pengujian, melakukan debug, dan menggunakan API REST Anda.
URL Swagger UI sesuai dengan titik akhir tempat Anda menyajikan berkas JSON spesifikasi OpenAPI Anda. Ini berarti bahwa Anda perlu menyediakan alamat web yang mengarah ke lokasi berkas JSON OpenAPI Anda. Swagger UI membaca berkas ini untuk membuat antarmuka yang mudah digunakan yang dapat diakses melalui URL tersebut. Struktur URL yang tepat dapat bervariasi karena konfigurasi server yang berbeda-beda.
Fitur Swagger UI
Swagger UI adalah alat yang hebat yang menyediakan berbagai fitur untuk menguji, memahami, dan memvisualisasikan API. Beberapa fitur disebutkan di bawah ini:
Fitur utama meliputi:
- Pengujian langsung API langsung di dalam dokumen
- Kontrol intuitif untuk parameter permintaan
- Pembuatan cuplikan kode untuk panggilan API
- Dukungan Markdown untuk pemformatan
- Alat untuk kolaborasi tim
- Visualisasi model data otomatis
- Organisasi dan pencarian titik akhir API
Parameter URL Swagger UI
Swagger UI memiliki berbagai parameter di URL untuk mengonfigurasi perilaku dan penampilannya. Ini memengaruhi bagaimana dokumentasi API ditampilkan menggunakan Swagger UI. Beberapa parameter URL Swagger UI yang paling umum digunakan adalah:
URL:
Ini menentukan URL berkas spesifikasi OpenAPI yang harus digunakan Swagger UI untuk menghasilkan dokumentasi API. Format URL adalah sebagai berikut:
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json
ConfigUrl:
configUrl menyediakan URL konfigurasi JSON yang menyesuaikan dan mengubah perilaku Swagger UI.
http://localhost:8080/swagger-ui/?configUrl=/path/to/your/config.json
deepLinking:
Ini memungkinkan tautan dalam ke operasi atau tag individual dalam dokumentasi API. Ini bermanfaat saat berbagi tautan langsung ke bagian tertentu dari dokumentasi.
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&deepLinking=true
oauth2RedirectUrl:
Ini memungkinkan pengguna untuk mengalihkan ke URL lain setelah otentikasi berhasil ketika API Anda memerlukan otentikasi OAuth 2.0.
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&oauth2RedirectUrl=https://your-app.example.com/oauth2-redirect
defaultModelsExpandDepth:
Ini menyesuaikan kedalaman default model dalam dokumentasi.
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&defaultModelsExpandDepth=2
Cara Menemukan URL Swagger UI
Beberapa orang bingung tentang di mana URL Swagger UI berada. URL ini dihasilkan berdasarkan konfigurasi proyek Anda. Untuk menemukan URL, ikuti langkah-langkah berikut:
- Pastikan proyek Anda dikonfigurasi untuk menghasilkan dokumentasi Swagger.
- Untuk mengakses Swagger UI, Anda perlu menggabungkan URL dasar API Anda dengan titik akhir dokumentasi Swagger. Ini akan menghasilkan URL Swagger UI Anda.
Misalnya, jika Anda menghosting API Anda di http://localhost:3000 dan titik akhir swagger Anda adalah /swagger-ui/, maka URL Swagger Anda akan menjadi http://localhost:8080/swagger-ui/.
Jika Anda masih kesulitan menemukan URL Swagger UI Anda, Anda dapat merujuk ke dokumentasi kerangka kerja atau pustaka yang Anda gunakan untuk menghasilkan API Anda. Ini akan membantu dalam memberikan informasi tentang cara mengakses URL untuk pengaturan spesifik Anda.
Cara Mengubah Jalur Default Swagger UI?
Jalur default Swagger UI Anda bergantung pada konfigurasi server Anda. Jalur ini dibangun berdasarkan lokasi dan tempat Anda menerapkan Swagger UI. Jalur URL default dapat diubah sesuai dengan persyaratan dan penerapan pengguna. Parameter URL di URL harus menunjuk ke lokasi berkas spesifikasi OpenAPI.
Ada banyak metode untuk mengubah jalur default URL Swagger UI.
Mengubah berkas konfigurasi Swagger (Apache dan Nginx):
Jika Anda menggunakan server web, Anda dapat mengubah konfigurasi server Anda untuk menangani permintaan di URL tertentu.
Apache:
Dalam kasus Apache, Anda dapat memodifikasi berkas konfigurasi Anda untuk membuat aturan penulisan ulang sehingga permintaan dapat dialihkan ke jalur Swagger UI Anda. Anda harus membuka berkas konfigurasi Anda, sering kali bernama 'httpd.conf' atau 'apache2.conf'. Tambahkan aturan penulisan ulang Anda untuk jalur yang Anda inginkan dalam berkas ini.
RewriteEngine On
RewriteRule ^/api-docs/(.*)$ /path/to/your/swagger-ui/$1 [L]
Anda dapat memulai ulang server Apache Anda agar perubahan diterapkan.
Nginx:
Jika Anda menggunakan Nginx, Anda harus memperbarui konfigurasi berkas server Anda untuk menentukan lokasi untuk menangani permintaan Anda. Di blok server, tambahkan lokasi Anda.
server {
listen 80;
server_name your-domain.com;
location /api-docs {
alias /path/to/your/swagger-ui;
index index.html;
}
}
Periksa kesalahan sintaks setelah membuat perubahan dan muat ulang Nginx Anda agar perubahan diterapkan.
Menggunakan kerangka kerja seperti Express.js:
Menggunakan Express.js, Anda dapat mengonfigurasi rute Anda untuk menangani permintaan Swagger UI.
Untuk menyajikan Swagger UI, Anda harus menentukan rute dalam berkas server Express.js Anda.
const express = require('express');
const app = express();
app.use('/custom-path', express.static('swagger-ui'));
app.listen(3000, () => {
console.log('Server is running on port 3000');
});
Ini akan memungkinkan Anda untuk mengakses Swagger UI Anda di 'custom-path' Anda.
Memanfaatkan Springboot untuk mengubah jalur default:
Dalam aplikasi Spring Boot, Anda dapat memodifikasi berkas 'application.properties' atau 'application.yml'. Anda dapat menambahkan properti berikut untuk mengubah jalur Swagger UI default di berkas 'application.properties' atau 'application.yml' Anda.
springfox.documentation.swagger-ui.path=/custom-path
Anda dapat mengganti '/custom-path' sesuai dengan jalur yang Anda inginkan.
Selanjutnya, Anda perlu mengonfigurasi bean untuk menyesuaikan jalur. Anda dapat memperluas 'WebMvcConfigurerAdapter' untuk mencapai ini.
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class SwaggerUIConfiguration implements WebMvcConfigurer {
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addRedirectViewController("/custom-path", "/swagger-ui.html");
}
}
Pastikan Anda memiliki dependensi yang diperlukan di Swagger untuk mencapai hasil ini.
Anda kemudian perlu mengonfigurasi kelas utama aplikasi Anda.
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("your.package.name"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Your API Documentation")
.version("1.0")
.build();
}
}
Ganti "your.package.name" dengan paket dasar pengontrol Anda.
Inisialisasi Swagger UI:
Anda dapat menyesuaikan parameter 'url' untuk mencerminkan jalur URL yang Anda inginkan. Ini akan memungkinkan Anda untuk mengubah jalur default Swagger UI. Saat menginisialisasi Swagger UI di JavaScript, Anda dapat membuat perubahan berikut.
const ui = SwaggerUIBundle({
url: "/custom-path/swagger.json",
});
Menggunakan Swagger UI untuk Menguji API
Sama seperti alat pengujian API lainnya, seperti Apidog, Swagger UI menyediakan cara yang efisien dan mudah digunakan untuk menguji API. Anda harus mengikuti langkah-langkah tertentu untuk melakukan debug dan menguji API Anda menggunakan situs Swagger . Klik pada Demo Langsung dan mulailah menjelajahi Swagger UI. Anda akan melihat jendela seperti ini terbuka.
Anda dapat menjelajahi beberapa metode HTTP/HTTPS seperti POST, GET, PUT, dll.
Anda dapat mengklik metode apa pun dan menjelajahinya. Jika Anda mengklik metode POST, Anda akan melihat opsi untuk mengunggah gambar dan memperbarui parameter metode. Anda dapat menekan 'Execute', dan permintaan Anda akan dieksekusi.
Anda dapat melihat respons terhadap permintaan POST dengan menggulir ke bawah.
Demikian pula, Anda dapat bekerja dengan metode lain yang diberikan dan melihat apa yang mereka lakukan. Ini akan memberi Anda gambaran yang baik tentang cara kerja Swagger UI.
Pertimbangkan Apidog untuk dokumentasi API yang lebih kuat di luar kemampuan Swagger UI. Apidog memungkinkan manajemen siklus hidup API penuh termasuk desain, mocking, pengujian, pembuatan versi, kolaborasi, dan banyak lagi.
Dengan fitur-fitur canggih seperti integrasi CI/CD dan alur kerja tim, Apidog menawarkan toolkit yang lebih lengkap untuk menyederhanakan pengiriman API. Platform komprehensifnya menskalakan pengembangan API dan meningkatkan produktivitas.
Memecahkan Masalah Swagger UI Localhost
Jika Anda menghadapi masalah dengan URL Swagger UI di localhost, ada beberapa langkah pemecahan masalah yang dapat Anda periksa untuk mendiagnosis dan menyelesaikan masalah tersebut.
- Pastikan server API Anda aktif dan berjalan. Swagger UI tidak dapat mengambil dokumentasi jika server Anda mengalami masalah saat berjalan.
- Periksa konfigurasi Swagger Anda untuk melihat apakah konfigurasi tersebut telah disiapkan dengan benar.
- Gunakan URL Swagger UI yang benar dengan titik akhir yang benar.
- Hapus cache browser Anda. Terkadang, kesalahan tak terduga dapat terjadi dengan data yang di-cache.
- Mulai ulang server API dan browser Anda setelah membuat perubahan apa pun.
- Periksa kembali format URL yang Anda gunakan untuk mengakses Swagger UI.
Kesimpulan
Sebagai kesimpulan, Swagger UI dengan cepat mendapatkan popularitas di kalangan pengembang karena teknik manajemen API yang luas. Ini menyediakan dokumentasi yang terstruktur dengan baik dan antarmuka yang mudah digunakan. Pengguna juga dapat memvisualisasikan model data saat melakukan pengujian API langsung, menjadikannya pilihan yang baik untuk pengujian dan debugging API.
Meskipun Swagger UI memiliki kelebihannya, ada juga beberapa batasan yang dapat dilihat pengguna saat menguji API. Ini menyediakan kolaborasi terbatas antara pengembang dan tidak mendukung integrasi dengan alat manajemen API lainnya.
