DEV Community

Cover image for Komut Satırından API Belgeleme Rehberi
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Komut Satırından API Belgeleme Rehberi

API belgeleri, biri spesifikasyonu düzenleyip referansı yeniden oluşturmayı unuttuğunda güncelliğini yitirir. Çözüm, dokümantasyonu manuel bir adım olmaktan çıkarmaktır. Belgeleri tek komutla üretebiliyorsanız, bu komutu CI'a bağlayabilir ve her birleştirmede çalıştırabilirsiniz.

Apidog'u bugün deneyin

Bunu terminalden yapmanın başka avantajları da vardır: komutlar betiklenebilir, inceleyebileceğiniz bir fark üretir ve bir yapay zekâ aracı ya da CI çalıştırıcısı bunları tarayıcı açmadan tetikleyebilir. GUI tıklaması yok, “dışa aktarmayı unutmadın mı?” derdi yok.

Bu kılavuz önce genel açık yolu gösterir: bir OpenAPI dosyasını tek komutla bağımsız bir HTML referansına veya Markdown dosyasına dönüştürmek. Ardından belgelerinizi doğrudan canlı bir projeden çeken Apidog CLI akışına geçeriz; böylece doğruluk kaynağı ve çıktı senkronize kalır. Arka plan için en iyi REST API dokümantasyon araçları ve ücretsiz API dokümantasyon araçları özetlerine de bakabilirsiniz.

Devam etmek için tek bir şeye ihtiyacınız var: bir OpenAPI 3.x dosyası. Bu komutların çoğu openapi.yaml veya openapi.json dosyalarını dönüşümlü olarak kabul eder.

Redocly CLI ile HTML referansı oluşturma

Redocly CLI, bir OpenAPI açıklamasını bağımsız bir HTML sayfasına dönüştürmenin hızlı bir yoludur. Spesifikasyonunuzu Redoc ile işler ve stiller, betikler ve içerik dahil her şeyi tek dosyada üretir.

Global olarak yükleyin veya npx ile çalıştırın:

npm install @redocly/cli -g
Enter fullscreen mode Exit fullscreen mode

Ardından spesifikasyonunuzu derleyin:

redocly build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Varsayılan olarak komut, mevcut dizine redoc-static.html yazar. Dosyayı tarayıcıda açarak tam API referansını görüntüleyebilirsiniz.

Çıktı yolunu kontrol etmek için --output kullanın:

redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

Akış basittir: bir girdi dosyası, bir komut, bir HTML yapıtı. Redocly; Swagger 2.0 ile OpenAPI 3.0 ve 3.1 açıklamalarını destekler.

Bu yaklaşımın sınırı şudur: build-docs yalnızca referans sayfası üretir. Uzun biçimli kılavuzlar, eğitimler ve başlangıç sayfaları bu çıktının dışında kalır.

Widdershins ile Markdown oluşturma

HTML yerine doküman sitenize, statik site oluşturucunuza veya deponuzdaki docs/ klasörüne ekleyebileceğiniz Markdown üretmek isteyebilirsiniz. Widdershins, OpenAPI, Swagger veya AsyncAPI tanımını Slate uyumlu Markdown'a dönüştürür.

Paketi npm üzerinden yükleyin:

npm install -g widdershins
Enter fullscreen mode Exit fullscreen mode

Spesifikasyonu dönüştürüp çıktıyı dosyaya yazın:

widdershins openapi.yaml -o api.md
Enter fullscreen mode Exit fullscreen mode

-o parametresini kaldırırsanız Widdershins çıktıyı standart çıktıya (stdout) yazar. Bu, çıktıyı başka bir komuta yönlendirmek için kullanışlıdır.

Kod örneklerindeki dil sekmelerini de ayarlayabilirsiniz:

widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Enter fullscreen mode Exit fullscreen mode

Widdershins, dokümantasyon hattınız Markdown tabanlıysa iyi bir seçenektir. Daha geniş bir dışa aktarma akışı için Markdown dışa aktarma özelliğine sahip API doküman oluşturucu rehberine bakabilirsiniz.

Redocly ve Widdershins için temel dezavantaj aynıdır: ikisi de statik dosya okur. API tanımınız tasarım aracındaki sürümden farklıysa, güncel olmayan spesifikasyonu belgelersiniz.

Apidog CLI ile canlı projeden belge oluşturma

Entegre akış burada fayda sağlar. Apidog açık kaynak değildir; ancak ücretsiz katmanı ve apidog-cli, ayrı araçları birleştirmeye alternatif sunar. Uç noktalarınız, şemalarınız ve yazılı belgeleriniz aynı projede yaşar; CLI ise bu projeden doğrudan dışa aktarım yapar.

CLI'yi yükleyin:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

İlk kurulum için Apidog CLI kurulum kılavuzu, Node sürümlerini ve PATH yapılandırmasını kapsar.

Kişisel erişim belirteciyle bir kez kimlik doğrulayın:

apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

Token saklanır; dolayısıyla sonraki çağrılarda tekrar iletmeniz gerekmez. Tüm işlemler proje kimliği üzerinden yürür. Komutları çalıştırmadan önce desteklenen bayrakları görmek için --help kullanın.

Spesifikasyonu projeye aktarma

API'niz mevcutta bir OpenAPI dosyasındaysa, dışa aktarılabilir canlı kaynak oluşturmak için onu projeye aktarın:

apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

apidog import; OpenAPI 3.x, Swagger 2.0, Postman ve Apidog formatlarını kabul eder. Böylece bir Postman koleksiyonunu veya mevcut bir Apidog dışa aktarımını da içe aktarabilirsiniz.

Spesifikasyon aktarıldıktan sonra, diğer dışa aktarma işlemlerinin kullandığı canlı kaynak olur.

İnsan tarafından okunabilir belge dışa aktarma

apidog export, OpenAPI, HTML, Markdown veya Postman çıktısı üretebilir. Önce sürümünüzün desteklediği format ve çıktı bayraklarını kontrol edin:

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Projenin dokümantasyonunu Markdown olarak dışa aktarmak için:

apidog export --project <projectId> --format markdown --output ./api-docs.md
Enter fullscreen mode Exit fullscreen mode

api-docs.md dosyasını açtığınızda, projenin güncel durumundan üretilen referansı görürsünüz.

HTML çıktısı için yalnızca formatı değiştirin:

apidog export --project <projectId> --format html --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

Taşınabilir bir spesifikasyon gerektiğinde yeniden OpenAPI olarak da dışa aktarabilirsiniz:

apidog export --project <projectId> --format openapi --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Projeniz birden fazla hizmet içeriyorsa, yalnızca belirli bir bölümü dışa aktarmak için sürümünüzün desteklediği kapsam ve kimlik bayraklarını inceleyin:

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Referans dışında yazılı kılavuzları yönetme

Şemadan üretilen referans, dokümantasyonun yalnızca yarısıdır. Başlangıç kılavuzları, kimlik doğrulama adımları ve geçiş notları gibi metin belgeleri de gerekir.

Apidog'da bunlar proje belge ağacında Markdown belgeleri olarak bulunur. CLI üzerinden doc komut grubuyla yönetilebilirler.

Önce kullanılabilir komutları inceleyin:

apidog doc --help
apidog doc list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

Komutu projenize karşı çalıştırın, JSON sonucunu inceleyin ve dönen agentHints.nextSteps önerilerini takip edin.

Bir komut JSON yükü gerektiriyorsa, CLI beklenen şemayı yazdırabilir. Dosyanızı göndermeden önce doğrulayarak eksik alanları yerelde yakalayabilirsiniz:

apidog cli-schema --help
Enter fullscreen mode Exit fullscreen mode

Doküman sitesi yayınlama

Referans ve kılavuzlar hazır olduğunda, yayınlanan dokümantasyonu terminalden de yönetebilirsiniz:

apidog docs-site --help
apidog shared-doc --help
Enter fullscreen mode Exit fullscreen mode

İsimlendirme farkını netleştirelim:

  • doc: Projenin API ağacındaki Markdown belgesidir.
  • docs-site: Barındırılan, herkese açık dokümantasyon sitesini yönetir.
  • shared-doc: Paylaşılabilir dokümantasyon bağlantılarını yönetir.

Terminalden herkese açık bir site tanımlamak için docs-site, yalnızca bir iş ortağıyla paylaşılacak bağlantı oluşturmak için shared-doc kullanın.

Bu sayede yayınlama da betiklenmiş bir adım olur: spesifikasyonu yeniden içe aktarır veya projede güncellersiniz, ardından yayınlama komutunu tekrar çalıştırırsınız. Barındırılan belgeler güncel içeriği yansıtır.

Bunu CI'a bağlayın

CLI kullanmanın temel nedeni tekrarlanabilirliktir. Komutlar yerelde çalışıyorsa pipeline içinde de çalışır.

Her çalıştırmada Markdown referansı oluşturan minimal GitHub Actions adımı şöyledir:

- name: Regenerate API docs
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Enter fullscreen mode Exit fullscreen mode

Aynı yapıyı redocly build-docs veya widdershins ile de kullanabilirsiniz. Belgeler, birinin hatırlaması gereken manuel iş olmaktan çıkar; her değişiklikte yeniden üretilen bir build yapıtına dönüşür.

Komutların tamamı için Apidog CLI eksiksiz kılavuzuna bakın.

Yaygın sorunlar

Yanlış veya eksik proje kimliği

Her Apidog export, doc ve docs-site çağrısı --project <projectId> gerektirir. Kimlik, projenin görünen adından değil proje ayarlarından alınır. Komut proje bulunamadı benzeri hata veriyorsa, önce proje kimliğini kontrol edin.

CI ortamında token ayarlanmamış

apidog login, token'ı çalıştıran makinede saklar. Her yeni CI çalıştırıcısı temiz ortamla başlar. Bu nedenle dışa aktarmadan önce aynı iş içinde giriş yapmanız gerekir:

apidog login --with-token $APIDOG_TOKEN
Enter fullscreen mode Exit fullscreen mode

Token'ı iş akışı dosyasına yazmayın; CI secret olarak saklayın.

Güncel olmayan dosya dışa aktarımları

Redocly ve Widdershins, kendilerine verdiğiniz dosyayı okur. openapi.yaml güncel değilse üretilen belgeler de güncel değildir. Apidog akışı, diskteki dosya yerine canlı projeden dışa aktarım yaparak bu sapmayı azaltır.

--help okumadan bayrak tahmin etmek

export, doc, docs-site ve shared-doc için desteklenen bayraklar CLI sürümüne göre değişebilir. Tahmin etmek yerine şu kalıbı kullanın:

apidog <command> --help
Enter fullscreen mode Exit fullscreen mode

Bu kısa kontrol, hatalı bayraklardan kaynaklanan başarısız derlemeleri önler.

Sonuç

Terminalden API dokümantasyonu üretmek, doğru çıktıyı seçmekle başlar:

  • Bağımsız HTML referansı için Redocly CLI kullanın.
  • Doküman sitenizde kullanılacak Markdown için Widdershins kullanın.
  • Referans, yazılı kılavuzlar ve yayınlanmış doküman sitesi için tek canlı kaynaktan dışa aktarım gerektiğinde Apidog CLI kullanın.

Her komut betiklenebilir; bu nedenle her biri CI içinde çalışabilir. Bir kez yapılandırın ve dokümantasyonunuz her değişiklikte kendini yenilesin.

CLI'yi edinip kendi projenizde dışa aktarma akışını denemek için Apidog'u indirin veya Apidog'un API-öncelikli iş akışına nasıl uyduğunu inceleyin.

Top comments (0)