Cara Membuat Spesifikasi OpenAPI dari Request yang Sudah Ada

Menulis spesifikasi OpenAPI dari awal dapat memakan banyak waktu, terutama jika API Anda sudah aktif dan berjalan. Banyak tim mewarisi proyek dengan sedikit atau tanpa dokumentasi, atau mereka bekerja dengan API yang dibangun dengan cepat selama pengembangan awal. Dalam kasus ini, cara paling praktis untuk membuat dokumentasi adalah dengan menghasilkan spesifikasi OpenAPI langsung dari permintaan API Anda yang sudah ada.

Panduan ini menjelaskan mengapa pendekatan ini berhasil, alat apa yang dapat membantu, dan bagaimana Anda dapat mengubah permintaan aktual menjadi spesifikasi OpenAPI yang bersih dan dapat digunakan kembali yang dapat dipercaya oleh tim Anda.

Metode 1: Pendekatan "Code-First"

Metode ini berfungsi jika Anda dapat menambahkan anotasi atau pustaka langsung ke kode aplikasi backend Anda.

Bagaimana Cara Kerjanya?

Anda menginstal pustaka di kerangka kerja web Anda yang memeriksa kode Anda—rute, pengontrol, dan model—dan menghasilkan spesifikasi OpenAPI secara langsung.

Pustaka Populer:

• Node.js (Express): swagger-jsdoc atau tsoa (TypeScript OpenAPI)
• Python (FastAPI/Flask): FastAPI memiliki ini bawaan! Flask dapat menggunakan flasgger atau flask-restx.
• Java (Spring Boot): springdoc-openapi
• .NET: Swashbuckle

Contoh dengan FastAPI (Python):

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    """
    Create a new item in the database.
    - **name**: The item's name
    - **price**: The item's price in USD
    """
    return item

# This code automatically generates a full OpenAPI spec at /docs or /openapi.json

Kelebihan:

• Selalu akurat: Spesifikasi berasal langsung dari kode yang berjalan.
• Perawatan rendah: Perbarui kode, dan spesifikasi diperbarui secara otomatis.

Kekurangan:

• Membutuhkan akses kode: Anda tidak dapat menggunakannya untuk API pihak ketiga atau warisan yang tidak Anda kontrol.
• Dapat mengacaukan kode: Anotasi OpenAPI yang ekstensif dapat membuat logika bisnis lebih sulit dibaca.

Metode 2: Pendekatan "Traffic Analysis"

Ini adalah pendekatan "outside-in" yang cerdas. Anda menangkap lalu lintas HTTP nyata antara klien dan API Anda, lalu menganalisisnya untuk menyimpulkan spesifikasi.

Bagaimana Cara Kerjanya?

Anda menggunakan alat yang bertindak sebagai proxy atau network sniffer. Semua lalu lintas API dirutekan melaluinya. Alat ini menganalisis permintaan dan respons—URL, metode, header, badan—dan membangun model API Anda.

Alat Populer:

• Akita Software: Secara otomatis mengamati lalu lintas API untuk membuat dan memantau spesifikasi.
• Membuat file HAR: Anda dapat menggunakan Alat Pengembang browser Anda (tab Jaringan) untuk merekam sesi dengan API Anda dan mengekspor sebagai file HAR (HTTP Archive). Beberapa alat dapat mengonversinya ke OpenAPI.

Proses:

1. Konfigurasi aplikasi atau klien Anda untuk merutekan lalu lintas melalui alat proxy.
2. Jalankan alur kerja API utama Anda (masuk, buat data, ambil data, dll.).
3. Alat mengamati pola dan menghasilkan spesifikasi OpenAPI pendahuluan.

Kelebihan:

• Sangat baik untuk API warisan/kotak hitam: Berfungsi tanpa perubahan kode atau kerja sama dari server.
• Berdasarkan penggunaan nyata: Menangkap titik akhir dan bentuk data yang benar-benar digunakan.

Kekurangan:

• Mungkin tidak lengkap: Hanya menghasilkan spesifikasi untuk titik akhir yang Anda panggil selama perekaman.
• Dapat melewatkan nuansa: Mungkin tidak secara akurat menyimpulkan semua batasan, bidang opsional, atau respons kesalahan.
• Overhead penyiapan: Membutuhkan intersepsi lalu lintas jaringan, yang bisa rumit di beberapa lingkungan.

Metode 3: Pendekatan "Request Collection"

Ini seringkali merupakan metode yang paling praktis dan efisien untuk pengembang dan tim. Anda menggunakan klien API canggih yang tidak hanya mengirimkan permintaan tetapi juga memahami desain API. Anda membangun kumpulan permintaan Anda, dan alat tersebut membantu Anda menyusun dan mengekspornya sebagai spesifikasi OpenAPI yang bersih.

Di sinilah kekuatan Apidog unggul. Ini dibangun untuk alur kerja ini.

Bagaimana Cara Kerjanya dengan Apidog?

1. Kirim Permintaan seperti Biasanya: Jangan ubah alur kerja Anda. Gunakan Apidog untuk menguji dan men-debug titik akhir API Anda yang sudah ada. Saat Anda mengirim permintaan GET, POST, PUT, dan DELETE, Apidog menangkap semua detailnya.

2. Biarkan Apidog Membangun Model: Di balik layar, saat Anda bekerja, Apidog mulai memahami struktur API Anda. Ia melihat titik akhir, parameter, badan permintaan, dan skema respons.

3. Atur ke dalam Dokumen: Apidog dapat mengubah permintaan menjadi dokumen API secara real-time. Permintaan ad-hoc Anda menjadi halaman dokumentasi API yang terstruktur dan dapat dinavigasi dalam alat. Anda dapat menambahkan deskripsi, mengelompokkan titik akhir ke dalam folder, dan membersihkan detail yang disimpulkan secara otomatis.

4. Ekspor Spesifikasi: Setelah koleksi Anda akurat dan dijelaskan dengan baik, Anda mengekspornya. Dan kemudian pengguna dapat mengekspor spesifikasi OpenAPI dalam format YAML atau JSON standar dengan satu klik. Spesifikasi ini siap digunakan dengan Swagger UI, diimpor ke alat lain, atau di-commit ke repositori Anda.

Kelebihan:

• Alur kerja alami: Sesuai dengan cara kerja pengembang (menguji API).
• Kontrol tinggi: Anda mengkurasi dan menyempurnakan spesifikasi saat Anda membangun koleksi.
• Komprehensif: Anda dapat memastikan semua titik akhir, respons kesalahan, dan metode autentikasi didokumentasikan.
• Kolaboratif: Tim dapat bekerja sama dalam koleksi permintaan yang sama.

Kekurangan:

• Membutuhkan upaya manual: Anda perlu memastikan Anda telah mencakup semua titik akhir. Ini tidak sepenuhnya otomatis dari lalu lintas.

Metode 4: Pendekatan "Manual Crafting"

Terkadang, Anda perlu membangun spesifikasi secara manual di editor seperti Swagger Editor atau Stoplight Studio. Ini sering dilakukan bersamaan dengan metode di atas.

1. Gunakan Koleksi Permintaan Anda sebagai Referensi: Buka koleksi Postman Anda, perintah cURL, atau proyek Apidog di layar kedua.
2. Bangun Spesifikasi Langkah demi Langkah: Untuk setiap titik akhir dalam referensi Anda, terjemahkan secara manual ke dalam OpenAPI YAML/JSON. Ini memaksa Anda untuk berpikir secara mendalam tentang setiap parameter dan respons.
3. Validasi dengan Contoh: Gunakan pratinjau editor untuk memastikan spesifikasi Anda sesuai dengan perilaku API yang sebenarnya.

Kelebihan:

• Pemahaman mendalam: Anda akan mengetahui setiap detail spesifikasi Anda.
• Presisi tertinggi: Anda dapat mendokumentasikan nuansa yang mungkin dilewatkan oleh alat otomatis.

Kekurangan:

• Sangat memakan waktu: Metode yang paling padat karya.
• Rentang kesalahan: Mudah membuat kesalahan ketik atau melupakan titik akhir.

Praktik Terbaik untuk Menghasilkan Spesifikasi OpenAPI dari Permintaan

Terlepas dari metode Anda, ikuti prinsip-prinsip ini:

1. Mulai Kecil: Pilih satu titik akhir inti (seperti GET /users). Hasilkan atau dokumentasikan sepenuhnya, lalu perluas.
2. Validasi Dini dan Sering: Gunakan spesifikasi OpenAPI untuk segera menghasilkan server tiruan (mock server). Apakah ia berperilaku seperti API Anda yang sebenarnya? Ini dengan cepat menangkap perbedaan.
3. Iterasi dan Sempurnakan: Spesifikasi pertama yang Anda hasilkan akan kasar. Perlakukan itu sebagai draf. Tambahkan deskripsi, contoh, dan perketat definisi skema.
4. Sertakan Respons Kesalahan: Ini sering terlewatkan. Pastikan spesifikasi Anda mendokumentasikan format respons kesalahan 4xx dan 5xx.
5. Jangan Lupakan Autentikasi: Dokumenkan bagaimana API Anda diamankan (Kunci API, OAuth2, dll.) di bagian securitySchemes.

Kesimpulan: Cetak Biru Anda Menanti

Menghasilkan spesifikasi OpenAPI dari permintaan yang sudah ada tidak hanya mungkin, tetapi merupakan keharusan praktis untuk membawa ketertiban pada proyek API yang sudah matang. Baik Anda memilih pustaka code-first, alat traffic-sniffing, atau klien API yang kuat seperti Apidog, Anda berinvestasi dalam kejelasan, otomatisasi, dan kolaborasi.

Metode yang Anda pilih tergantung pada konteks Anda: kontrol atas basis kode, batasan waktu, dan alur kerja tim. Tetapi tujuannya sama: untuk mengubah pengetahuan implisit yang terkandung dalam log permintaan Anda, perintah cURL, dan pemahaman internal menjadi kontrak eksplisit yang dapat dibaca mesin yang dapat mendorong API Anda maju.

Berhentilah membiarkan kompleksitas API Anda hidup dalam bayangan. Mulailah dengan permintaan yang sudah Anda miliki, gunakan alat yang tepat, dan bangun cetak biru OpenAPI yang esensial itu. Diri Anda di masa depan dan semua orang yang perlu menggunakan API Anda akan berterima kasih.