Cara Sederhanakan Dokumentasi API dengan Swagger

Posted on September 1, 2024

Anda pernah mencoba mendokumentasikan API Anda menggunakan Swagger?

Biasanya, setelah menonton tutorial dan membaca dokumentasi resmi OpenAPI, kita cenderung menulis semuanya dalam satu file YAML. Kita mendefinisikan komponen, skema, dan lainnya di satu tempat.

Ini mengakibatkan file YAML dengan ratusan baris kode, yang sulit dibaca, dimodifikasi, dan di-debug dalam jangka panjang.

Satu-satunya solusi yang ditawarkan adalah menggunakan SwaggerHub milik OpenAPI, yang sayangnya tidak gratis.

Tidak ideal, bukan?

Pendekatan Modular untuk Dokumentasi API yang Lebih Baik

Ada cara yang lebih baik untuk mendekati dokumentasi API dengan Swagger: dengan menggunakan pendekatan modular.

Alih-alih menulis semua kode dalam satu file, kita dapat membaginya menjadi beberapa file YAML yang lebih kecil, masing-masing mewakili bagian tertentu dari API.

Misalnya, kita dapat membuat folder terpisah untuk parameter, sumber daya, respons, dan skema.

Dengan cara ini, struktur kode menjadi lebih teratur dan mudah dipahami.

Menggabungkan File YAML dengan swagger-cli

Setelah kita memiliki file YAML yang terstruktur dengan baik, kita dapat menggabungkannya menjadi satu file menggunakan alat swagger-cli.

Berikut adalah langkah-langkahnya:

  1. Buat folder terpisah untuk setiap bagian dari API.
  • Misal: parameters, resources, responses, dan schemas.
  1. Buat file YAML untuk setiap bagian, dengan nama yang deskriptif.
  • Contoh: users.yaml di folder resources.
  1. Ekspor setiap file YAML sebagai modul.
  2. Buat file YAML utama yang mengimpor semua modul YAML yang telah dibuat.
  3. Gunakan swagger-cli untuk menggabungkan semua file YAML menjadi satu.

Berikut contoh perintah yang dapat digunakan:

npx swagger-cli bundle src/openapi.yaml -outfile _build/openapi.yaml -type yaml

Perintah ini akan menggabungkan semua file YAML di folder src dan menyimpannya dalam satu file di folder _build.

Mengujinya di Swagger Live Editor

Setelah file YAML gabungan selesai dibuat, Anda dapat mencobanya di Swagger Live Editor.

Cukup salin dan tempelkan konten file YAML ke editor dan lihat bagaimana dokumentasi API Anda ditampilkan.

Keuntungan Pendekatan Modular

Pendekatan modular menawarkan beberapa keuntungan:

  • Kemudahan pemeliharaan: Kode menjadi lebih mudah dipahami dan diubah.
  • Kemudahan debugging: Jika terjadi kesalahan, Anda dapat dengan mudah menemukan sumbernya.
  • Kolaborasi yang lebih baik: Setiap orang dapat mengerjakan bagian yang berbeda dari API tanpa perlu khawatir tentang konflik kode.
  • Struktur yang lebih baik: Kode menjadi lebih terorganisir dan mudah di-navigate.

Kesimpulan

Dengan menggunakan pendekatan modular untuk mendokumentasikan API dengan Swagger, Anda dapat membuat proses dokumentasi menjadi lebih efisien dan efektif.

Anda akan memiliki kode yang lebih terorganisir, mudah diubah, dan mudah di-debug.

Selain itu, Anda dapat memanfaatkan kekuatan swagger-cli untuk menggabungkan semua file YAML menjadi satu file yang dapat digunakan di Swagger Live Editor.

Untuk melihat contoh implementasi pendekatan modular ini, Anda dapat mengunjungi repositori GitHub saya.