Jika Anda telah mengadopsi Bruno, Anda pasti sudah tahu daya tariknya. Koleksi Anda tersimpan sebagai file .bru biasa di repo Git Anda, yang dikontrol versinya bersama kode, tanpa memerlukan akun cloud. Ini adalah jawaban yang bersih dan offline-first untuk klien API yang ingin menguasai data Anda.
Namun cepat atau lambat seseorang mengajukan pertanyaan yang tidak dapat dijawab dengan baik oleh Bruno: “Di mana dokumennya? Bisakah Anda mengirimi saya tautan?” Di situlah tim mengalami kendala. Bruno dibuat untuk mengirim permintaan, bukan untuk menerbitkan portal dokumentasi yang dapat dibagikan. Panduan ini membahas pembuatan dokumentasi API Bruno secara jujur, apa yang diberikan Bruno kepada Anda, apa yang tidak, dan cara menghasilkan serta meng-host dokumen dari spesifikasi Anda saat Anda membutuhkan URL asli untuk diberikan kepada konsumen.
tombol
Apa yang sebenarnya dibutuhkan tim dari dokumentasi API
Sebelum menilai alat apa pun, ada baiknya untuk menentukan target. Ketika orang mengatakan "dokumentasi API", mereka biasanya mengacu pada tiga hal yang bekerja bersama:
- URL yang dapat dibagikan. Pengembang frontend, mitra, dan QA perlu membaca dokumen tanpa mengkloning repo Anda atau menginstal klien. Tautan di Slack seharusnya berfungsi.
- Dokumen yang tetap sinkron. Dokumentasi yang menyimpang dari API yang sebenarnya lebih buruk daripada tidak ada sama sekali, karena mengirim orang ke arah yang salah dengan keyakinan. Dokumen harus melacak spesifikasi.
- Pengalaman "coba" yang interaktif. Membaca deskripsi endpoint itu bagus; mengirimkan permintaan nyata ke endpoint yang didokumentasikan, dengan otentikasi dan contoh payload yang sudah terisi, adalah yang mengubah dokumen menjadi referensi yang dapat digunakan.
Penuhi ketiganya dan dokumen Anda menjadi satu-satunya sumber kebenaran. Lewati satu saja dan orang-orang akan kembali bertanya langsung kepada Anda, yang tidak dapat diskalakan.
Kisah dokumentasi Bruno
Mari kita bersikap adil kepada Bruno, karena Bruno melakukan beberapa hal dengan baik di sini.
Koleksi Bruno mudah dibaca oleh manusia. Format .bru adalah teks biasa, sehingga seorang insinyur yang menjelajahi repo dapat membuka file permintaan dan melihat metode, URL, header, dan badan. Bruno juga mendukung blok docs per permintaan dan tampilan dokumentasi Markdown di dalam aplikasi, sehingga Anda dapat melampirkan penjelasan yang menjelaskan fungsi sebuah endpoint. Karena semuanya ada di Git, catatan-catatan tersebut ditinjau dalam permintaan tarik seperti perubahan lainnya. Bagi tim internal yang bekerja di basis kode, itu adalah bentuk dokumentasi yang sah.
Kesenjangan yang jujur adalah publikasi. Bruno tidak memiliki portal dokumentasi publik bawaan, terhosting, dan dihasilkan secara otomatis. Tidak ada tombol "publikasikan" yang mengubah koleksi Anda menjadi situs web di URL yang stabil dengan domain khusus. Tampilan dokumen dalam aplikasi terlihat oleh orang-orang yang sudah menginstal Bruno dan telah mengkloning koleksi, yang merupakan audiens yang paling tidak membutuhkan dokumen.
Jadi, tim berimprovisasi. Solusi umum termasuk mengekspor koleksi atau file OpenAPI dan memasukkannya ke generator dokumen statis terpisah, menghubungkan situs dokumen di CI, atau memelihara README yang ditulis tangan yang diperbarui seseorang berdasarkan ingatan. Ini bisa berfungsi, tetapi mereka menambah pipeline build untuk dipelihara dan tempat kedua di mana informasi bisa menyimpang. Dokumentasi bukan lagi hasil kelas satu dari alat yang Anda uji; itu adalah proyek sampingan.
Prinsip docs-as-code
Cara yang lebih bersih untuk memikirkannya, dan ini adalah sesuatu yang sudah setengah diyakini oleh pengguna Bruno: perlakukan dokumentasi Anda sebagai produk dari spesifikasi Anda, bukan artefak terpisah.
Dalam alur kerja docs-as-code, API Anda dijelaskan sekali dalam spesifikasi yang dapat dibaca mesin, biasanya OpenAPI. Spesifikasi tersebut tersimpan di Git, ditinjau dalam permintaan tarik, dan berfungsi sebagai kontrak. Dokumentasi, server mock, dan SDK klien semuanya dihasilkan dari spesifikasi tersebut. Ketika kontrak berubah, perubahan tersebut ditinjau di satu tempat, dan semua hal di bawahnya mengikuti.
Keuntungannya adalah tidak ada tugas "perbarui dokumen" terpisah yang perlu dilupakan. Dokumen adalah representasi dari spesifikasi. Jika spesifikasi benar dan ditinjau, maka dokumen juga benar. Ini adalah prinsip yang diisyaratkan Bruno dengan menyimpan koleksi di Git, tetapi berhenti sebelum langkah publikasi.
Hasilkan dan host dokumen dari spesifikasi Anda sebagai gantinya
Inilah celah yang Apidog dibangun untuk ditutup. Apidog mempertahankan model mental yang berpusat pada spesifikasi dan ramah Git yang sama, kemudian menambahkan bagian yang tidak dimiliki Bruno: ia menghasilkan situs dokumentasi interaktif yang di-host langsung dari spesifikasi Anda, tanpa memerlukan pipeline build terpisah.
Arahkan Apidog ke spesifikasi OpenAPI Anda dan itu akan secara otomatis menghasilkan portal dokumentasi. Hasilnya adalah:
- Di-host di URL yang dapat dibagikan, sehingga siapa pun dengan tautan dapat membaca dokumen tanpa menginstal apa pun.
- Dapat dipasang di domain kustom, sehingga dokumen dapat berada di
docs.nama_perusahaan_anda.comdan sesuai dengan merek Anda. - Interaktif, dengan panel "coba" bawaan yang mengirimkan permintaan nyata menggunakan parameter, header, dan otentikasi yang didokumentasikan.
- Dihasilkan dari spesifikasi, sehingga dokumen mencerminkan apa yang sebenarnya dinyatakan oleh API daripada salinan tulisan tangan yang bisa menyimpang.
Karena spesifikasi yang sama juga mendorong pengujian dan mocking Apidog, Anda tidak memelihara tiga deskripsi dari satu API. Anda mendeskripsikannya sekali dan menggunakannya kembali.
Panduan: dari spesifikasi ke URL yang dapat dibagikan
Berikut adalah versi singkat dari publikasi dokumen dari spesifikasi OpenAPI.
| Langkah | Tindakan | Hasil |
|---|---|---|
| 1 | Impor atau tulis spesifikasi OpenAPI Anda di Apidog | Endpoint, skema, dan contoh terisi secara otomatis |
| 2 | Buka pengaturan dokumentasi proyek | Dokumen dihasilkan dari spesifikasi, siap untuk dikonfigurasi |
| 3 | Pilih visibilitas dan (opsional) domain kustom | Dokumen bersifat publik, pribadi, atau dilindungi kata sandi |
| 4 | Publikasikan | Situs dokumen live dan terhosting dibuat di URL yang stabil |
| 5 | Bagikan tautannya | Konsumen membaca dokumen dan menjalankan permintaan "coba" |
Jika Anda sudah memiliki koleksi Bruno, Anda bisa mengubahnya ke OpenAPI terlebih dahulu, lalu mengimpor spesifikasi tersebut. Dari sana, langkah publikasi sama. Intinya adalah bahwa pembuatan dan hosting dokumen adalah suatu *fitur*, bukan pipeline yang Anda rakit sendiri.
Menjaga dokumen tetap sinkron saat spesifikasi berubah
URL dokumen hanya berguna jika tetap akurat. Mode kegagalan dengan pengaturan improvisasi adalah seseorang mengirimkan perubahan endpoint dan melupakan dokumennya.
Ketika dokumen dihasilkan dari spesifikasi, risiko itu berkurang. Anda mengedit spesifikasi, perubahan spesifikasi melewati tinjauan seperti perubahan kode lainnya, dan dokumen yang dipublikasikan mencerminkan status baru. Tidak ada dokumen paralel yang perlu diingat. Tambahkan bidang ke skema respons dan itu muncul di dokumen; usanglah suatu endpoint dan dokumen akan mengatakannya. Pekerjaan yang sudah Anda lakukan untuk menjaga kontrak tetap benar adalah pekerjaan yang sama yang menjaga dokumen tetap benar.
Ini adalah hasil praktis dari prinsip docs-as-code: kebenaran menjadi efek samping dari alur kerja yang Anda inginkan, bukan tugas terpisah yang bergantung pada disiplin.
FAQ
Bisakah Bruno menghasilkan dan meng-host dokumentasi API publik?
Bruno menyediakan file koleksi .bru yang mudah dibaca dan tampilan dokumen Markdown dalam aplikasi, keduanya ditinjau di Git. Itu tidak menyertakan portal dokumen publik bawaan, terhosting, dan dihasilkan secara otomatis dengan URL yang dapat dibagikan. Untuk menerbitkan dokumen publik dari Bruno, tim biasanya mengekspor spesifikasi dan menjalankan generator dokumen statis terpisah, yang menambahkan pipeline untuk dipelihara.
Bagaimana cara mendapatkan URL dokumen yang dapat dibagikan dari API saya?
Deskripsikan API Anda dalam spesifikasi OpenAPI, lalu gunakan alat yang menghasilkan dokumen terhosting darinya. Di Apidog, Anda mengimpor spesifikasi, mengonfigurasi visibilitas, secara opsional melampirkan domain kustom, dan memublikasikan. Outputnya adalah situs dokumentasi live di URL yang stabil, dengan panel "coba" interaktif, yang dapat Anda bagikan secara langsung.
Apakah saya harus meninggalkan koleksi Bruno saya untuk memublikasikan dokumen?
Tidak. Anda dapat mengubah koleksi Bruno yang ada menjadi OpenAPI dan mengimpor spesifikasi tersebut ke dalam alat dokumen. Endpoint, skema, dan contoh Anda akan terbawa, dan Anda tetap menjaga spesifikasi di bawah kontrol versi. Migrasi berada pada lapisan spesifikasi, sehingga kebiasaan docs-as-code yang Anda bangun dengan Bruno masih berlaku.
tombol