API belgeleri, birisi bir spesifikasyonu düzenlediği ve referansı yeniden oluşturmayı unuttuğu anda güncelliğini yitirir. Çözüm, dokümantasyonu manuel bir adım olarak ele almayı bırakmaktır. Belgeleri tek bir komutla üretebilirseniz, bu komutu CI'a bağlayabilir ve her birleştirme işleminde çalıştırmasına izin verebilirsiniz.
Bunu terminalden yapmanın başka avantajları da var. Komutlar betiklenebilir, inceleyebileceğiniz bir fark bırakırlar ve bir yapay zeka aracı veya bir CI çalıştırıcısı, kimsenin bir tarayıcı açmasına gerek kalmadan bunları tetikleyebilir. GUI tıklaması yok, "dışa aktarmayı unutmadın mı" derdi yok.
Bu kılavuz önce genel açık yolu gösteriyor: bir OpenAPI dosyasını tek bir komutla bağımsız bir HTML referansına veya bir Markdown dosyasına dönüştürmek. Ardından, belgelerinizi doğrudan canlı bir projeden çeken Apidog CLI rotasına daha derinlemesine iniyor, böylece doğruluk kaynağı ve çıktı senkronize kalıyor. Eğer arka plan hakkında daha fazla bilgi edinmek isterseniz, en iyi REST API dokümantasyon araçları ve bilmeye değer ücretsiz API dokümantasyon araçları hakkındaki özetimize 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 bir HTML referansı oluşturun
Redocly CLI, bir OpenAPI açıklamasını şık, bağımsız bir HTML sayfasına dönüştürmenin en hızlı yoludur. Spesifikasyonunuzu Redoc ile işler ve her şeyi (stiller, betik ve içerik) herhangi bir yerde barındırabileceğiniz veya bir ekip arkadaşınıza e-postayla gönderebileceğiniz tek bir dosyaya yazar.
Genel olarak yükleyin veya yüklemeyi atlayıp npx ile çalıştırın:
npm install @redocly/cli -g
Ardından spesifikasyonunuzu işaret edin:
redocly build-docs openapi.yaml
Varsayılan olarak bu, mevcut dizine redoc-static.html yazar. Bu dosyayı bir tarayıcıda açın ve eksiksiz, üç panelli bir API referansına sahip olursunuz. Dosya adını veya yolunu kontrol etmek için --output kullanın:
redocly build-docs openapi.yaml --output docs/index.html
Tüm iş akışı bu. Bir girdi dosyası, bir komut, bir HTML yapıtı. Swagger 2.0 ve OpenAPI 3.0/3.1 açıklamalarıyla çalışır, bu nedenle çoğu mevcut spesifikasyon değişiklik yapmadan işlenir. Takas alanı: build-docs size bir referans sayfası ve başka hiçbir şey vermez. Uzun biçimli kılavuzlar, eğitimler ve başlangıç sayfaları bunun dışında kalır.
Widdershins ile Markdown Oluşturma
Bazen HTML istemezsiniz. Bir doküman sitesine, statik site oluşturucuya veya bir deponun docs/ klasörüne bırakabileceğiniz Markdown istersiniz. Widdershins, bir OpenAPI, Swagger veya AsyncAPI tanımını Slate uyumlu Markdown'a dönüştürür.
Npm'den yükleyin:
npm install -g widdershins
Ardından spesifikasyonunuzu dönüştürün ve çıktıyı -o ile bir dosyaya gönderin:
widdershins openapi.yaml -o api.md
-o'yu çıkarırsanız, Widdershins çıktıyı standart çıktıya (stdout) yazdırır, bu da onu başka bir yere yönlendirmek isterseniz kullanışlıdır. Kod örnekleri için dil sekmelerini de değiştirebilirsiniz:
widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Widdershins, doküman hattınız Markdown tabanlı olduğunda iyi bir seçimdir. Eğer daha geniş bir Markdown dışa aktarma akışı oluşturuyorsanız, Markdown dışa aktarma özelliğine sahip bir API doküman oluşturucu kullanma kılavuzumuz ilgili araçları kapsar. Hem Redocly hem de Widdershins için dezavantaj aynıdır: statik bir dosyayı okurlar. API tanımınız bir tasarım aracında yaşıyorsa ve disktaki dosyadan sapıyorsa, dünün spesifikasyonunu belgeliyorsunuz demektir.
Apidog CLI ile canlı bir projeden belge oluşturma
Entegre yolun karşılığını verdiği yer burasıdır. Apidog açık kaynak değildir, ancak ücretsiz katmanı ve apidog-cli, ayrı araçları bir araya getirmeye bir alternatif sunar: uç noktalarınız, şemalarınız ve yazılı belgeleriniz tek bir projede yaşar ve CLI, bu projeden talep üzerine dışa aktarım yapar. Hiçbir şey sapmaz, çünkü dışa aktarım, ekibinizin düzenlediği aynı kaynağı okur.
CLI'yi npm'den yükleyin:
npm install -g apidog-cli
İlk kez kurulum yapıyorsanız, Apidog CLI kurulum kılavuzumuz Node sürümlerini ve PATH kurulumunu kapsar. Ardından kişisel erişim belirteciyle bir kez kimlik doğrulayın:
apidog login --with-token <TOKEN>
Token saklanır, bu yüzden her çağrıda onu iletmezsiniz. Buradan itibaren her şey bir proje kimliğine göre çalışır. Çalıştırmadan önce tam bayrakları görmek için herhangi bir komuta --help ekleyin.
Bir spesifikasyonu projeye aktarın
API'niz zaten bir OpenAPI dosyasında yaşıyorsa, CLI'nin dışa aktaracak bir şeye sahip olması için onu bir projeye aktarın:
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
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ı aynı şekilde çekebilirsiniz. Spesifikasyon aktarıldıktan sonra, diğer her şeyin okuduğu canlı kaynak haline gelir.
İnsan tarafından okunabilir belgeleri dışa aktarın
Bu temel komuttur. apidog export OpenAPI, HTML, Markdown veya Postman yazar, bu nedenle sürümünüzün tam format ve çıktı bayraklarını görmek için önce --help komutunu çalıştırın, ardından projenin dokümantasyonunu Markdown'a aktarın:
apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
api-docs.md dosyasını açın ve projenin mevcut durumundan oluşturulmuş tam bir referansa sahip olun. Bunun yerine HTML mi istiyorsunuz? Tek bir bayrağı değiştirin:
apidog export --project <projectId> --format html --output ./api-docs.html
Aşağıya aktarılacak taşınabilir bir spesifikasyon istediğinizde OpenAPI'ye geri de aktarabilirsiniz:
apidog export --project <projectId> --format openapi --output ./openapi.json
Projeniz birden fazla hizmet içeriyorsa ve yalnızca bir kısmının belgelenmesini istiyorsanız, dışa aktarım kapsamı daraltmayı destekler. Tek bir proje bu şekilde hizmet başına bir doküman dosyası gönderebileceği için sürümünüzdeki kapsam ve kimlik bayrakları için apidog export --help komutunu kontrol edin.
Sadece referansı değil, yazılı kılavuzları da yönetin
Şemanızdan oluşturulan bir referans hikayenin sadece yarısıdır. Diğer yarısı ise metindir: başlangıç kılavuzları, kimlik doğrulama adımları, geçiş notları. Apidog'da bunlar projenin belge ağacında Markdown belgeleri olarak yaşar ve CLI bunları doc komut grubuyla yönetir.
Grup yardımını okuyarak başlayın, böylece sürümünüzün gönderdiği tam bayraklarla çalışırsınız:
apidog doc --help
apidog doc list --project <projectId>
Oradan akış, CLI'daki diğer her şeyle aynı şekildedir: komutu projenize karşı çalıştırın, JSON sonucunu okuyun ve geri verdiği agentHints.nextSteps'i takip edin. Bir komut bir JSON yükü istediğinde, CLI beklediği şemayı yazdırabilir ve herhangi bir şey göndermeden önce dosyanızı buna göre doğrulayabilir, böylece eksik bir alanı başarısız bir çağrıda değil, kendi makinenizde yakalarsınız. Tam doğrulama alt komutu için apidog cli-schema --help komutunu kontrol edin.
Bir doküman sitesi yayınlayın
Referans ve kılavuzlar hazır olduğunda, yayınlanan dokümantasyonu terminalden de yönetebilirsiniz. İki komut bunu kapsar ve önce onların yardımını okumak, tahmin edilen bir bayrağı kurtarır:
apidog docs-site --help
apidog shared-doc --help
İnsanları şaşırtan bir isimlendirme notu: bir doc, projenin API ağacındaki bir Markdown belgesidir, docs-site barındırılan, herkese açık dokümantasyon sitesini yönetir ve shared-doc paylaşılabilir dokümantasyon bağlantılarını yönetir. Herkese açık bir siteyi bir kullanıcı arayüzünde tıklayarak değil de terminalden tanımlamak istediğinizde docs-site'a, sadece bir ortağa vermek için bir bağlantı istediğinizde ise shared-doc'a ulaşın. Karşılığı ise yayınlamanın betiklenmiş bir adım haline gelmesidir: spesifikasyonunuz değiştiğinde, projeyi yeniden içe aktarır veya düzenler, ardından yayınlama komutunu tekrar çalıştırırsınız ve barındırılan belgeler güncellemeyi yansıtır.
Bunu CI'ya bağlayın
Bunun herhangi birini CLI'dan çalıştırmanın nedeni tekrarlanabilirliktir. Komutlar yerel olarak çalıştığında, bir pipeline'da da çalışırlar. Her push işleminde Markdown referansınızı yeniden oluşturan ve commit eden minimal bir GitHub Actions adımı şöyle görünür:
- 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
redocly build-docs veya widdershins ile değiştirildiğinde şekil aynıdır. Belgeler, birisinin yapmayı hatırladığı bir angarya olmaktan çıkar ve kendini yeniden oluşturan bir yapı yapıtına dönüşür. Komut referansını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 insan tarafından okunabilir adında değil, proje ayarlarındadır. Bir komut proje hakkında hata veriyorsa, bunun nedeni neredeyse her zaman budur.
Token CI'da ayarlanmamış. apidog login token'ı çalıştıran makinede saklar. Yeni bir CI çalıştırıcısında saklanmış bir token yoktur, bu nedenle herhangi bir dışa aktarımdan önce aynı işte login --with-token komutunu çalıştırmanız gerekir. Token'ı bir sır olarak saklayın, asla iş akışı dosyasında değil.
Güncelliğini yitirmiş dosya dışa aktarımları. Redocly ve Widdershins, onlara verdiğiniz her dosyayı okur. Eğer openapi.yaml dosyanız güncel değilse, belgeleriniz de güncel değildir. Apidog rotasının tam da bu sapmayı önlediği şey, disktaki bir dosyadan değil, canlı projeden dışa aktarım yapmasıdır.
--help okumak yerine bayrakları tahmin etmek. export, doc, docs-site ve shared-doc için tam bayraklar CLI sürümüne göre değişebilir. apidog <command> --help komutunu çalıştırın ve yarı hatırladığınız bir bayrak yerine yazdırdıklarından yola çıkın. Bu iki saniye sürer ve başarısız bir derlemeyi önler.
Sonuç
Bir API'yi terminalden belgelemek, doğru çıktıyı seçmeye bağlıdır. Bağımsız bir HTML referansı istediğinizde Redocly CLI'ye, bir doküman sitesi için Markdown istediğinizde Widdershins'e ve referansın yanı sıra yazılı kılavuzlar ve yayınlanmış bir sitenin tamamını tek bir canlı kaynaktan dışa aktarmak istediğinizde Apidog CLI'ye başvurun. Son seçenek, belgelerinizi dürüst tutan seçenektir, çünkü dışa aktarım ve ekibinizin düzenlediği şey aynı projedir.
Buradaki her komut betiklenebilir, bu da her birinin CI'da olması gerektiği anlamına gelir. Bir kez ayarlayın ve dokümantasyonunuz her değişiklikte kendini yeniler. CLI'yi edinmek ve kendi projenizde dışa aktarma akışını denemek için Apidog'u indirin veya Apidog'un API-öncelikli bir iş akışına nasıl uyduğu hakkında daha fazla bilgi edinin.