Dengan plugin IDEA Apidog atau beberapa plugin Swagger, Anda dapat dengan mudah membuat dokumentasi API dari kode, mengatasi masalah penulisan dokumen dari awal.
Namun, bahkan setelah endpoint ditulis dan dokumen dibuat, Anda mungkin masih merasa tidak yakin: Apakah desain API sudah cukup baik? Apakah dokumentasi sudah terstandardisasi? Apakah ada area yang dapat ditingkatkan lebih lanjut?
Terutama dalam kolaborasi tim, Anda ingin dokumen API Anda mudah dipahami oleh rekan tim secara sekilas. Kejelasan penamaan dan kelengkapan informasi secara langsung memengaruhi pengalaman mereka dalam menggunakan API Anda.
Apidog baru-baru ini meluncurkan beberapa fitur AI untuk membantu Anda lebih lanjut mengoptimalkan dokumentasi API pada tahap ini. Baik Anda meningkatkan detail endpoint yang sudah ada atau mengimpor dokumen API yang sudah ada dari tempat lain, AI dapat memberikan saran praktis.
Di bawah ini, kami akan membahas cara menggunakan AI di Apidog untuk membuat dokumentasi API yang lebih terstandardisasi. Sebelum kita mulai, pastikan Anda telah memperbarui Apidog ke versi terbaru, mengaktifkan fitur AI, dan mengonfigurasi model AI.
Mengimpor dari Dokumentasi yang Ada
Terkadang Anda perlu memigrasikan dokumentasi API dari sumber lain ke Apidog. Jika dokumen dalam format standar, Apidog secara native mendukung beberapa metode impor: Anda dapat membuat dokumen dari kode melalui plugin IDEA, mengimpor spesifikasi OpenAPI/Swagger, atau memigrasikan dari alat lain seperti Postman.
Namun dalam beberapa kasus, dokumentasi Anda mungkin tidak dalam format standar ini. Misalnya, tim sebelumnya mendokumentasikan endpoint dalam Markdown, mengelola deskripsi bidang di Word, atau menemukan definisi endpoint dalam log chat atau email. Memasukkan setiap bidang secara manual dari sumber non-standar ini ke Apidog bisa sangat menantang.
Dalam situasi ini, Anda dapat menggunakan fitur Ubah skema dengan AI untuk membantu entri data. Misalkan Anda memiliki konten Markdown seperti ini:
| name | desc | type | required |
| --- | --- | --- | --- |
| usePaging | Whether to enable pagination | boolean | true |
| offset | Starting position (required when pagination is enabled) | int | false |
| pageSize | Number of items per page (required when pagination is enabled) | int | false |
| minPrice | Minimum price (unit: cents) | int | false |
| maxPrice | Maximum price (unit: cents) | int | false |
| brand | Brand code | string | false |
| categoryId | Product category ID | int | false |
| sortRule | Sorting rule: 1 → Sales priority, 2 → Price ascending, 3 → Price descending | enum(int) | false |
| keyword | Search keyword (fuzzy match on product name) | string | false |Cukup salin parameter dan tanyakan kepada AI: "Konversi konten ini menjadi parameter endpoint, pastikan untuk mengidentifikasi tipe dan bidang yang wajib diisi."
AI akan secara otomatis mendeteksi nama bidang, tipe data, status wajib diisi, dan deskripsi, lalu mengonversi semuanya ke dalam format skema standar Apidog. Jika enum disertakan, AI juga akan mengaturnya ke dalam tipe enum yang sesuai untuk Anda.
AI Membantu Anda Menyempurnakan Detail API
Setelah mengimpor informasi dasar, langkah selanjutnya adalah menyempurnakan detailnya.
Jika Anda tidak yakin tentang nama bidang, gunakan fitur Penamaan AI. AI akan memberikan saran penamaan yang lebih akurat sesuai dengan spesifikasi endpoint dan panduan desain API.
Anda juga dapat menggunakan AI untuk melengkapi secara otomatis deskripsi bidang untuk penjelasan yang lebih jelas dan lengkap.
Pembuatan data tiruan adalah kekuatan AI lainnya. Seringkali kita tahu apa yang diwakili oleh suatu bidang tetapi tidak yakin nilai contoh apa yang harus digunakan. AI akan secara otomatis menghasilkan data contoh yang masuk akal berdasarkan tipe dan deskripsi bidang.
Pemeriksaan Kelengkapan Dokumentasi API: Menghindari Kelalaian
Ketika dokumentasi terlihat hampir lengkap, Anda mungkin masih bertanya-tanya apakah ada informasi penting yang terlewat. Pada titik ini, gunakan Pemeriksaan Kelengkapan Dokumentasi API Apidog untuk melihat apakah ada sesuatu yang terabaikan.
AI akan memindai dokumentasi API Anda yang sudah ada dari berbagai perspektif untuk mengidentifikasi informasi yang hilang atau tidak lengkap. Kemudian, AI akan membuat laporan terperinci yang menilai setiap item ulasan, membantu Anda dengan cepat melihat di mana dokumen API Anda memerlukan perbaikan.
Laporan tersebut tidak hanya memberi tahu Anda apa yang harus dilakukan—tetapi juga menjelaskan alasannya. Misalnya, Anda mungkin telah mendokumentasikan format respons yang berhasil tetapi tidak skenario kesalahan yang mungkin terjadi; Anda mungkin memiliki deskripsi bidang dasar tetapi tidak memiliki batasan penggunaan atau persyaratan format.
Anda dapat meningkatkan dokumentasi API Anda dengan mengikuti saran yang diberikan dalam laporan.
Pemeriksaan Kepatuhan Endpoint: Memastikan Konsistensi
Selain lengkap, dokumentasi API juga perlu distandardisasi dengan baik. Dalam satu endpoint, penamaan harus mengikuti gaya yang konsisten, tipe bidang harus didefinisikan dengan jelas dan benar, dan struktur respons harus logis. Detail-detail ini memainkan peran kunci dalam membuat dokumen Anda mudah dibaca dan dipelihara.
Fitur pemeriksaan kepatuhan endpoint Apidog memeriksa dokumentasi Anda dari berbagai sudut pandang. Misalnya, jika beberapa bidang dinamai dengan kata kerja sementara yang lain menggunakan kata benda, AI akan menandai inkonsistensi tersebut dan merekomendasikan gaya penamaan yang seragam.
Ini juga memeriksa apakah definisi bidang mengikuti standar yang konsisten, seperti menghindari gaya penulisan kasus campuran (mixed casing), penggunaan garis bawah (underscore) dan camelCase secara bersamaan, atau singkatan yang tidak konsisten, lalu memberikan saran yang jelas tentang cara memperbaiki masalah ini.
Ringkasan
Membuat dokumentasi API yang jelas dan terstandardisasi sangat penting. Fitur seperti kasus uji yang dihasilkan AI, bergantung pada kualitas dokumen Anda—semakin lengkap dan konsisten dokumen tersebut, semakin akurat dan berguna kasus uji yang dihasilkan.
Anda tidak perlu menggunakan setiap fitur AI sekaligus atau merombak alur kerja Anda saat ini.
Ini adalah proses bertahap. Anda dapat memulai dengan mengimpor dokumentasi Anda yang sudah ada dan kemudian perlahan-lahan menerapkan fitur AI untuk memperbaiki dan menyempurnakannya. Jika Anda tidak yakin dengan suatu saran, Anda dapat membiarkan semuanya tidak berubah dan mengunjunginya kembali nanti ketika Anda memiliki konteks yang lebih banyak.
Seiring waktu, Anda secara alami akan mendapatkan pemahaman yang lebih baik tentang standar dokumentasi API. AI tidak hanya membantu memperbaiki masalah langsung—tetapi juga membantu Anda mengembangkan kebiasaan dokumentasi yang lebih baik.