Bruno'dan API Belgeleri Nasıl Oluşturulur ve Barındırılır?

Bruno'yu kullanıyorsanız güçlü tarafını biliyorsunuzdur: koleksiyonlarınız Git deponuzda düz .bru dosyaları olarak yaşar, kodla birlikte sürüm kontrolüne girer ve bulut hesabı gerektirmez. Bu, verilerinizi sahiplenmek isteyen API istemcilerine karşı temiz, çevrimdışı öncelikli bir yaklaşımdır.

Apidog'u bugün deneyin

Ancak ekip büyüdükçe şu soru kaçınılmaz hale gelir: “API belgeleri nerede? Bana bir bağlantı gönderebilir misiniz?” Bruno burada sınırlı kalır. Bruno istek göndermek ve koleksiyonları Git içinde yönetmek için iyidir; paylaşılabilir, barındırılan bir API dokümantasyon portalı yayınlamak için tasarlanmamıştır. Bu yazıda Bruno’nun dokümantasyon tarafında ne sunduğunu, neyi sunmadığını ve OpenAPI spesifikasyonundan paylaşılabilir belge URL’si üretmek için nasıl ilerleyebileceğinizi ele alacağız.

Ekiplerin API dokümantasyonundan gerçekten beklediği şey

Bir API dokümantasyon aracını değerlendirirken hedefi netleştirmek gerekir. Pratikte ekiplerin ihtiyaç duyduğu üç ana şey vardır:

• Paylaşılabilir URL: Frontend geliştiricileri, QA ekipleri veya iş ortakları depoyu klonlamadan ve Bruno kurmadan belgeyi okuyabilmelidir.
• Senkronize kalan içerik: Dokümantasyon gerçek API’den ayrışırsa güvenilirliğini kaybeder. Belgeler API sözleşmesini takip etmelidir.
• Etkileşimli deneme alanı: Kullanıcılar parametreleri, header’ları, auth bilgisini ve örnek payload’ları görüp aynı ekrandan istek gönderebilmelidir.

Bu üç koşul sağlandığında dokümantasyon tek doğru kaynak haline gelir. Aksi halde ekipler yine Slack mesajlarına, ekran görüntülerine veya elle güncellenen README dosyalarına geri döner.

Bruno’nun dokümantasyon yaklaşımı

Bruno bazı dokümantasyon ihtiyaçlarını iyi karşılar.

Bruno koleksiyonları insan tarafından okunabilir .bru dosyalarıdır. Bir geliştirici repoyu açıp metod, URL, header ve body bilgilerini doğrudan inceleyebilir. Ayrıca Bruno, her istek için docs bloğu ve uygulama içinde Markdown dokümantasyon görünümü destekler.

Örneğin bir .bru dosyasında istek bilgisi ve açıklama birlikte tutulabilir:

meta {
  name: Get user
  type: http
}

get {
  url: {{baseUrl}}/users/{{userId}}
  body: none
  auth: bearer
}

docs {
  Bu endpoint, verilen userId için kullanıcı detaylarını döndürür.
}

Bu yaklaşım dahili ekipler için kullanışlıdır çünkü dokümantasyon da kod gibi Git içinde gözden geçirilebilir.

Sınırlama ise yayınlama adımındadır. Bruno’nun yerleşik, barındırılan ve otomatik oluşturulan bir genel API dokümantasyon portalı yoktur. Koleksiyonunuzu özel alan adına sahip sabit bir web sitesine dönüştüren bir “publish” akışı sunmaz.

Sonuç olarak Bruno’daki dokümantasyon çoğunlukla şu kişiler için görünürdür:

• Bruno’yu kurmuş olanlar
• Koleksiyonu klonlamış olanlar
• Repo erişimi bulunanlar

Yani dokümantasyona en az ihtiyaç duyan iç ekip üyeleri.

Yaygın geçici çözümler

Bruno kullanan ekipler genellikle şu yollardan birini dener:

1. Bruno koleksiyonunu veya OpenAPI dosyasını dışa aktarır.
2. Ayrı bir statik dokümantasyon aracı kullanır.
3. CI içinde belge sitesi üretir.
4. Elle güncellenen bir README.md tutar.

Bu yöntemler çalışabilir, ancak ek bakım maliyeti getirir. Artık API istemcisi, spesifikasyon, testler ve belgeler arasında ikinci bir senkronizasyon katmanı oluşur.

Tipik problem şudur:

Endpoint değişti
↓
Kod güncellendi
↓
Test güncellendi
↓
Dokümantasyon unutuldu

Bu da tüketicilere eski veya yanlış bilgi verilmesine neden olur.

Kod olarak dokümantasyon prensibi

Daha sürdürülebilir yaklaşım, dokümantasyonu ayrı bir çıktı olarak değil, API spesifikasyonunun ürünü olarak ele almaktır.

Kod olarak belgeler iş akışında, API genellikle OpenAPI gibi makine tarafından okunabilir bir spesifikasyonda tanımlanır. Bu spesifikasyon:

• Git içinde tutulur
• Pull request’lerde incelenir
• API sözleşmesi olarak kullanılır
• Dokümantasyon, mock server ve testler için kaynak olur

Örnek minimal OpenAPI tanımı:

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0

paths:
  /users/{userId}:
    get:
      summary: Kullanıcı detayını getir
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Kullanıcı başarıyla döndürüldü
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string

Bu modelde belgeler spesifikasyondan oluşturulur. Spesifikasyon doğruysa, dokümantasyon da aynı kaynağı takip eder.

Spesifikasyondan belge oluşturup barındırma

Bruno’nun eksik bıraktığı yayınlama adımını Apidog gibi araçlarla tamamlayabilirsiniz. Apidog, OpenAPI odaklı çalışma modelini destekler ve spesifikasyonunuzdan etkileşimli, barındırılan bir dokümantasyon sitesi oluşturur.

Apidog’u OpenAPI spesifikasyonunuza bağladığınızda şu çıktıları alırsınız:

• Paylaşılabilir bir dokümantasyon URL’si
• İsteğe bağlı özel alan adı desteği
• Etkileşimli “dene” paneli
• Parametre, header, auth ve örnek body bilgileriyle çalıştırılabilir istekler
• Spesifikasyondan oluşturulan güncel belge içeriği

Böylece aynı API tanımını hem dokümantasyon hem test hem de mock senaryoları için kullanabilirsiniz.

Adım adım: OpenAPI’den paylaşılabilir belge URL’sine

Aşağıdaki akış, OpenAPI spesifikasyonundan barındırılan dokümantasyon üretmek için temel uygulama yoludur.

Adım	Eylem	Sonuç
1	OpenAPI spesifikasyonunuzu Apidog'a aktarın veya yazın	Endpoint'ler, şemalar ve örnekler otomatik olarak dolar
2	Projenin dokümantasyon ayarlarını açın	Belgeler spesifikasyondan oluşturulur ve yapılandırmaya hazır hale gelir
3	Görünürlüğü ve isteğe bağlı özel alan adını seçin	Belgeler herkese açık, özel veya parola korumalı olabilir
4	Yayınlayın	Sabit URL'de barındırılan canlı dokümantasyon sitesi oluşur
5	Bağlantıyı paylaşın	Kullanıcılar belgeleri okur ve etkileşimli istekleri çalıştırır

Bruno koleksiyonunuz varsa pratik akış şu şekilde olabilir:

Bruno koleksiyonu
↓
OpenAPI spesifikasyonu
↓
Apidog'a import
↓
Dokümantasyon ayarları
↓
Yayınlanmış belge URL'si

Buradaki önemli nokta, belge sitesini elle oluşturmak veya ayrı bir pipeline yazmak yerine spesifikasyonu yayınlanabilir bir dokümantasyon kaynağına dönüştürmektir.

Belgeleri spesifikasyon değiştikçe güncel tutma

Bir belge URL’si yalnızca güncel kaldığında değerlidir. En sık yaşanan problem, endpoint değiştiğinde dokümantasyonun unutulmasıdır.

Spesifikasyon tabanlı akışta değişiklik süreci daha nettir:

OpenAPI değişir
↓
Pull request açılır
↓
Sözleşme incelenir
↓
Dokümantasyon aynı kaynaktan güncellenir

Örneğin yanıt şemasına yeni bir alan eklediğinizde bu alan dokümantasyonda da görünür. Bir endpoint’i kullanımdan kaldırdığınızda, bu bilgi de spesifikasyondan belgeye yansır.

Bu yaklaşımın ana faydası şudur: dokümantasyonu güncel tutmak ayrı bir angarya olmaktan çıkar, API sözleşmesini doğru tutma işinin doğal sonucu haline gelir.

Sıkça Sorulan Sorular

Bruno genel API dokümantasyonu oluşturup barındırabilir mi?

Bruno, okunabilir .bru koleksiyon dosyaları ve uygulama içi Markdown dokümantasyon görünümü sunar. Bunlar Git içinde incelenebilir. Ancak Bruno, paylaşılabilir URL’ye sahip yerleşik ve barındırılan bir genel dokümantasyon portalı içermez. Genel belge yayınlamak için genellikle OpenAPI dışa aktarma ve ayrı bir dokümantasyon aracı gerekir.

API’mden paylaşılabilir belge URL’si nasıl alabilirim?

API’nizi OpenAPI spesifikasyonunda tanımlayın ve bu spesifikasyondan barındırılan dokümantasyon oluşturan bir araç kullanın. Apidog’da spesifikasyonu içe aktarabilir, görünürlüğü ayarlayabilir, isteğe bağlı özel alan adı ekleyebilir ve belge sitesini yayınlayabilirsiniz.

Belgeleri yayınlamak için Bruno koleksiyonlarımı bırakmak zorunda mıyım?

Hayır. Mevcut Bruno koleksiyonunuzu OpenAPI’ye dönüştürüp bu spesifikasyonu dokümantasyon aracına aktarabilirsiniz. Böylece Bruno ile geliştirdiğiniz Git tabanlı çalışma alışkanlığını korurken paylaşılabilir dokümantasyon URL’si de elde edebilirsiniz.