Apa itu spesifikasi OpenAPI?

Spesifikasi OpenAPI, sebelumnya dikenal sebagai Swagger, menjelaskan berbagai aspek API. Spesifikasi OpenAPI (spesifikasi) menjelaskan titik akhir, parameter, dan respons API. Spesifikasi OpenAPI ditulis dalam YAML atau JSON dan digunakan oleh alat untuk menghasilkan dokumentasi, kasus pengujian, dan pustaka klien. Dengan memiliki spesifikasi OpenAPI, pembangun API dapat memastikan bahwa API mereka dijelaskan secara akurat, lebih mudah diakses, dan lebih mudah diintegrasikan di berbagai aplikasi dan layanan.

Berikut adalah mengapa Anda harus mempertimbangkan untuk memiliki spesifikasi OpenAPI untuk API Anda:

• Dokumentasikan API dengan cara yang distandarkan. Dokumentasikan spesifikasi API dalam format yang konsisten dan dapat dibaca manusia.
• Buat SDK klien. Gunakan alat seperti Kiota untuk mengotomatiskan pembuatan pustaka klien dalam berbagai bahasa pemrograman.
• Buat API tiruan. Buat server tiruan berdasarkan spesifikasi API, yang membantu Anda selama tahap awal pengembangan ketika API aktual belum diimplementasikan.
• Meningkatkan kolaborasi. Berikan tim yang berbeda (front end, back end, QA) pemahaman yang jelas tentang kemampuan dan batasan API, yang membantu anggota tim baru mengikuti dengan cepat.
• Menyederhanakan pengujian dan validasi. Mengotomatiskan validasi permintaan dan respons API terhadap spesifikasi, yang memudahkan untuk mengidentifikasi perbedaan.
• Integrasikan dengan alat manajemen API. Integrasikan, sebarkan, dan pantau API Anda dengan mudah dengan banyak alat dan gateway manajemen API, seperti Azure API Center dan Azure API Management.
• Menyederhanakan konfigurasi gateway API. Gunakan spesifikasi OpenAPI untuk mengonfigurasi gateway API dan mengotomatiskan tugas seperti perutean, transformasi, dan pengaturan berbagi sumber daya lintas asal.

Dengan menggunakan spesifikasi OpenAPI, Anda dapat membuat API yang dirancang dengan baik dan didokumenkan secara konsisten. Mereka juga lebih dapat dipertahankan dan lebih mudah digunakan baik secara internal maupun oleh konsumen eksternal.

Belum memiliki spesifikasi OpenAPI?

Menulis spesifikasi dengan tangan untuk API yang sudah ada membutuhkan waktu, dan spesifikasi itu menyimpang dari apa yang benar-benar dilakukan API. Opsi lain adalah merekam apa yang dikembalikan API dan menghasilkan spesifikasi dari itu.

Approach	Apa yang Anda dapatkan	Apa yang harus diperhatikan
Tulis dengan tangan	Kontrol penuh atas deskripsi dan contoh	Dibutuhkan waktu, dan menyimpang dari API yang sebenarnya
Buat dari anotasi kode	Spesifikasi yang tetap sinkron dengan kode Anda	Anda memerlukan akses ke kode API, dan kerangka kerja harus mendukungnya
Hasilkan itu dari lalu lintas yang direkam	Spesifikasi untuk API apa pun yang dapat Anda panggil, termasuk yang bukan milik Anda	Ini hanya mencakup permintaan yang Anda rekam, jadi uji bagian-bagian API yang Anda perlukan

Dev Proxy merekam permintaan dan respons antara aplikasi Anda dan API, dan menghasilkan spesifikasi OpenAPI dari mereka. Untuk langkah-langkahnya, lihat Menghasilkan spesifikasi OpenAPI.

Langkah selanjutnya

Hasilkan spesifikasi OpenAPI