Bruno'yu benimsediyseniz, çekiciliğini zaten biliyorsunuzdur. Koleksiyonlarınız Git deponuzda düz .bru dosyaları olarak, kodla birlikte sürüm kontrollü olarak yaşar ve bulut hesabı gerektirmez. Verilerinize sahip olmak isteyen API istemcilerine temiz, çevrimdışı öncelikli bir cevaptır.
Ancak er ya da geç birileri Bruno'nun iyi cevaplayamadığı bir soru sorar: "Belgeler nerede? Bana bir bağlantı gönderebilir misiniz?" İşte ekiplerin duvara çarptığı yer burasıdır. Bruno, istek göndermek için tasarlanmıştır, paylaşılabilir bir dokümantasyon portalı yayınlamak için değil. Bu kılavuz, Bruno API dokümantasyon oluşturmayı dürüstçe ele alıyor: Bruno'nun size ne verdiğini, ne vermediğini ve tüketicilere vermek üzere gerçek bir URL'ye ihtiyacınız olduğunda spesifikasyonunuzdan belgeleri nasıl oluşturup barındıracağınızı açıklıyor.
Ekiplerin API belgelerinden aslında neye ihtiyacı var?
Herhangi bir aracı yargılamadan önce, hedefi tanımlamak faydalıdır. İnsanlar "API dokümantasyonu" dediğinde, genellikle birlikte çalışan üç şeyi kastederler:
- Paylaşılabilir bir URL. Frontend geliştiricilerin, iş ortaklarının ve QA ekiplerinin, depolarını klonlamadan veya bir istemci yüklemeden belgeleri okuyabilmesi gerekir. Slack'teki bir bağlantının çalışması yeterli olmalıdır.
- Senkronize kalan belgeler. Gerçek API'den uzaklaşan dokümantasyon, hiç olmamasından daha kötüdür, çünkü insanları güvenle yanlış yöne gönderir. Belgeler spesifikasyonu takip etmelidir.
- Etkileşimli bir "dene" deneyimi. Uç nokta açıklamalarını okumak iyidir; belgelenmiş uç noktaya, doldurulmuş kimlik doğrulama ve örnek yüklerle gerçek bir istek göndermek, belgeleri kullanılabilir bir referansa dönüştüren şeydir.
Bu üçünü de başarırsanız, belgeleriniz tek doğru kaynak haline gelir. Birini kaçırırsanız, insanlar doğrudan size sormaya geri döner, ki bu ölçeklenemez.
Bruno'nun dokümantasyon hikayesi
Bruno'ya karşı dürüst olalım, çünkü bu konuda bazı şeyleri iyi yapıyor.
Bruno'nun koleksiyonları insan tarafından okunabilir. .bru formatı düz metindir, bu nedenle depoyu tarayan bir mühendis bir istek dosyasını açıp metodu, URL'yi, başlıkları ve gövdeyi görebilir. Bruno ayrıca istek başına bir docs bloğunu ve uygulama içinde bir Markdown dokümantasyon görünümünü de destekler, böylece bir uç noktanın ne yaptığını açıklayan metinleri ekleyebilirsiniz. Her şey Git'te olduğu için, bu notlar diğer değişiklikler gibi çekme isteklerinde incelenir. Kod tabanında yaşayan dahili bir ekip için bu, meşru bir dokümantasyon şeklidir.
Dürüst boşluk yayınlamadır. Bruno'nun yerleşik, barındırılan, otomatik olarak oluşturulan bir genel dokümantasyon portalı yoktur. Koleksiyonunuzu özel bir alan adıyla sabit bir URL'de bir web sitesine dönüştüren bir "yayınla" düğmesi yoktur. Uygulama içi belgeler görünümü, Bruno'yu zaten kurmuş ve koleksiyonu klonlamış kişiler tarafından görülebilir; bu da tam da belgelere en az ihtiyaç duyan kitledir.
Bu yüzden ekipler doğaçlama yapar. Yaygın geçici çözümler arasında koleksiyonun veya bir OpenAPI dosyasının dışa aktarılması ve ayrı bir statik belge oluşturucuya beslenmesi, CI'da bir belge sitesi oluşturulması veya birinin hafızasından güncellediği el yazısı bir README'nin sürdürülmesi yer alır. Bunlar işe yarayabilir, ancak sürdürülecek bir derleme hattı ve bilgilerin sapabileceği ikinci bir yer eklerler. Dokümantasyon artık test ettiğiniz aracın birinci sınıf bir çıktısı değil; bir yan projedir.
Kod olarak belgeler prensibi
Bunu düşünmenin daha temiz bir yolu var ve Bruno kullanıcılarının zaten yarı yarıya inandığı bir yol: dokümantasyonunuzu ayrı bir yapıt olarak değil, spesifikasyonunuzun bir ürünü olarak değerlendirin.
Kod olarak belgeler iş akışında, API'niz tipik olarak OpenAPI olmak üzere makine tarafından okunabilir bir spesifikasyonda bir kez tanımlanır. Bu spesifikasyon Git'te yaşar, çekme isteklerinde incelenir ve sözleşme görevi görür. Dokümantasyon, sahte sunucular ve istemci SDK'ları hepsi ondan oluşturulur. Sözleşme değiştiğinde, değişiklik tek bir yerde incelenir ve aşağı akışta her şey onu takip eder.
Avantajı, unutulacak ayrı bir "belgeleri güncelle" görevinin olmamasıdır. Belgeler spesifikasyonun bir yorumudur. Spesifikasyon doğru ve incelenmişse, belgeler de doğrudur. Bruno'nun koleksiyonları Git'te tutarak işaret ettiği ilke budur, ancak yayınlama adımında yetersiz kalır.
Bunun yerine spesifikasyonunuzdan belge oluşturun ve barındırın
İşte bu boşluğu Apidog kapatmak için inşa edilmiştir. Apidog, aynı spesifikasyon odaklı, Git dostu zihinsel modeli korur, ardından Bruno'nun dışarıda bıraktığı parçayı ekler: ayrı bir derleme hattına ihtiyaç duymadan, doğrudan spesifikasyonunuzdan etkileşimli, barındırılan bir dokümantasyon sitesi oluşturur.
Apidog'u OpenAPI spesifikasyonunuza yönlendirin ve otomatik olarak bir dokümantasyon portalı üretir. Sonuç şunlardır:
- Paylaşılabilir bir URL'de barındırılır, böylece bağlantıya sahip herkes hiçbir şey yüklemeden belgeleri okuyabilir.
- Özel bir alan adına bağlanabilir, böylece belgeler
docs.sirketiniz.comadresinde yaşayabilir ve markanızla eşleşebilir. - Belgelenmiş parametreleri, başlıkları ve kimlik doğrulamayı kullanarak gerçek istekler gönderen yerleşik bir "dene" paneliyle etkileşimlidir.
- Spesifikasyondan oluşturulur, böylece belgeler el yazısı bir kopyanın kaybolmasına kıyasla API'nin gerçekte neyi beyan ettiğini yansıtır.
Aynı spesifikasyon Apidog'un test ve sahteciliğini de yönettiği için, bir API'nin üç açıklamasını sürdürmek zorunda kalmazsınız. Onu bir kez tanımlar ve yeniden kullanırsınız.
Adım Adım: spesifikasyondan paylaşılabilir URL'ye
İşte bir OpenAPI spesifikasyonundan belge yayınlamanın kısa versiyonu.
| Adım | Eylem | Sonuç |
|---|---|---|
| 1 | OpenAPI spesifikasyonunuzu Apidog'a aktarın veya yazın | Uç noktalar, şemalar ve örnekler otomatik olarak dolar |
| 2 | Projenin dokümantasyon ayarlarını açın | Belgeler spesifikasyondan oluşturulur, yapılandırılmaya hazırdır |
| 3 | Görünürlüğü ve (isteğe bağlı olarak) özel bir alan adını seçin | Belgeler herkese açık, özel veya parola korumalıdır |
| 4 | Yayınla | Sabit bir URL'de canlı, barındırılan bir belge sitesi oluşturulur |
| 5 | Bağlantıyı paylaşın | Tüketiciler belgeleri okur ve "dene" isteklerini çalıştırır |
Zaten bir Bruno koleksiyonunuz varsa, onu önce OpenAPI'ye dönüştürebilir, ardından bu spesifikasyonu içe aktarabilirsiniz. Oradan yayınlama adımı aynıdır. Buradaki önemli nokta, belgeleri oluşturmanın ve barındırmanın kendinizin birleştirdiği bir süreç değil, mevcut bir olanak olmasıdır.
Spesifikasyon değiştikçe belgeleri senkronize tutmak
Bir belge URL'si ancak doğru kalırsa kullanışlıdır. Doğaçlama kurulumlardaki başarısızlık modu, birinin bir uç nokta değişikliği göndermesi ve belgeleri unutmasıdır.
Belgeler spesifikasyondan oluşturulduğunda, bu risk azalır. Spesifikasyonu düzenlersiniz, spesifikasyon değişikliği diğer kod değişiklikleri gibi gözden geçirilir ve yayınlanan belgeler yeni durumu yansıtır. Hatırlanması gereken paralel bir belge yoktur. Bir yanıt şemasına bir alan ekleyin ve belgelerde görünür; bir uç noktayı kullanımdan kaldırın ve belgeler bunu belirtir. Sözleşmeyi doğru tutmak için zaten yaptığınız çalışma, belgeleri doğru tutan çalışmadır.
Kod olarak belgeler ilkesinin pratik getirisi budur: doğruluk, disipline bağlı ayrı bir angarya olmaktan ziyade, zaten isteyeceğiniz bir iş akışının yan etkisi haline gelir.
Sıkça Sorulan Sorular
Bruno, genel API dokümantasyonu oluşturabilir ve barındırabilir mi?
Bruno, okunabilir .bru koleksiyon dosyaları ve uygulama içi Markdown belge görünümü sunar, her ikisi de Git'te incelenir. Paylaşılabilir bir URL'ye sahip yerleşik, barındırılan, otomatik olarak oluşturulmuş bir genel belge portalı içermez. Bruno'dan genel belgeleri yayınlamak için ekipler genellikle bir spesifikasyonu dışa aktarır ve ayrı bir statik belge oluşturucu çalıştırır, bu da sürdürülecek bir süreç ekler.
API'mden paylaşılabilir bir belge URL'sini nasıl alabilirim?
API'nizi bir OpenAPI spesifikasyonunda tanımlayın, ardından ondan barındırılan belgeleri oluşturan bir araç kullanın. Apidog'da spesifikasyonu içe aktarır, görünürlüğü yapılandırır, isteğe bağlı olarak özel bir alan adı eklersiniz ve yayınlarsınız. Çıktı, etkileşimli bir "dene" paneliyle, doğrudan paylaşabileceğiniz, sabit bir URL'de canlı bir dokümantasyon sitesidir.
Belgeleri yayınlamak için Bruno koleksiyonlarımı terk etmek zorunda mıyım?
Hayır. Mevcut bir Bruno koleksiyonunu OpenAPI'ye dönüştürebilir ve bu spesifikasyonu bir belge aracına aktarabilirsiniz. Uç noktalarınız, şemalarınız ve örnekleriniz aktarılır ve spesifikasyonu sürüm kontrolü altında tutarsınız. Taşıma spesifikasyon katmanında gerçekleşir, bu nedenle Bruno ile geliştirdiğiniz kod olarak belgeler alışkanlıkları hala geçerlidir.