DEV Community

Cover image for En İyi Hafif API Dokümantasyon CLI Araçları
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

En İyi Hafif API Dokümantasyon CLI Araçları

Bir OpenAPI dosyanız var ve ondan dokümanlar çıkarmak istiyorsunuz. Bir hizmet kurmak, bir portala giriş yapmak veya npm'nin yarısını çeken bir derleme adımı eklemek istemiyorsunuz. Belirtimeyi okuyan ve size herhangi bir yerde barındırabileceğiniz bir Markdown dosyası veya tek bir HTML sayfası veren tek bir komut istiyorsunuz.

Apidog'u bugün deneyin

Bu liste işte bunun içindir. Buradaki her araç küçüktür: tek bir ikili dosya, bir npx tek satırlık komut veya bir kez kurup unuttuğunuz bir paket. Hızlı başlarlar, çok az veya hiç yapılandırma gerektirmezler ve tam bir platformu arkalarında sürüklemeden dokümantasyon işini yaparlar. Bazıları mevcut bir doküman sitesine bırakabileceğiniz Markdown çıkarır. Bazıları tek başına bir HTML dosyası çıkarır. Hepsi CI'da ve terminalde çalışır; asıl mesele de budur.

Daha geniş dokümantasyon platformları alanını istiyorsanız, en iyi REST API dokümantasyon araçları derlemesi GUI ağırlıklı tarafı kapsar. Bu parça, terminal öncelikli ve düşük ayak izli bir kesittir. Bir dokümantasyon üretecinin ne okuduğuna dair resmi referans için OpenAPI Şartnamesi, aşağıdaki her aracın ayrıştırdığı doğruluk kaynağıdır.

Bir CLI aracını API dokümantasyonu için "hafif" yapan nedir?

Hafiflik, güçsüz olmakla ilgili değildir. Ayak izi ve sürtünme ile ilgilidir. Dört şey bunu belirler:

  • Kurulum boyutu ve bağımlılıklar: Tek bir ikili dosya veya tek bir npm paketi, bir çerçeveyi yener. Bir doküman sayfası oluşturmak dil çalışma zamanı, paketleyici ve eklenti sistemi kurmak anlamına geliyorsa, çıktı neye benzerse benzesin bu hafif değildir.
  • Başlangıç ve yapılandırma: En iyi araçlar belirtiminizi okur ve sıfır yapılandırma ile çıktı üretir. Komutu openapi.yaml dosyasına yönlendirirsiniz ve bir dosya geri alırsınız.
  • Tek amaçlı çıktı: Aşağıdaki her araç tek bir şey yapar: belirtim içeri, dokümanlar dışarı. Markdown veya HTML üretir; başka hiçbir şey ekli değildir.
  • Her yerde çalışma: GUI yok, açık araçlar için giriş yok, canlı tutulacak sunucu yok. Dizüstü bilgisayarınızda ve CI görevinde aynı şekilde çalışır.

Daha geniş bir ücretsiz seçenekler yelpazesi için ücretsiz API dokümantasyon araçları listesinde platformlar bulunur; bu yazı bunun CLI odaklı bölümüdür.

Şimdi araçlar, en küçüğünden başlayarak.

Widdershins

Widdershins, bu işin olabileceği en küçük halidir. Bir OpenAPI 3, Swagger 2 veya AsyncAPI dosyasını Markdown'a dönüştüren tek bir npm paketidir. Bir site oluşturmaz veya sunucu çalıştırmaz; size bir .md dosyası verir ve aradan çekilir.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

Ürettiği Markdown Slate uyumludur; bu da çıktıyı daha sonra statik bir siteye beslemek istediğinizde kullanışlıdır.

Yararlı bayraklar:

# YAML ön bilgisini atla
widdershins openapi.yaml --omitHeader -o api-docs.md

# Gösterilecek kod örneği dillerini belirle
widdershins openapi.yaml \
  --language_tabs 'shell:Shell' 'javascript:JavaScript' \
  -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

En iyi kullanım: Belirtim içeriğini taahhüt edebileceğiniz, karşılaştırabileceğiniz ve istediğiniz doküman sistemine ekleyebileceğiniz Markdown'a aktarmak.

Sınırlar: Yalnızca Markdown alırsınız. Stil, etkileşimli "deneyin" paneli veya barındırılan çıktı yoktur. Widdershins bir dönüştürücüdür; Markdown'ı siteye dönüştüren başka bir araçla eşleştirmeniz gerekir.

OpenAPI Generator (doküman üreteçleri)

OpenAPI Generator en çok istemci SDK'ları ile bilinir, ancak yalnızca belirtiminiz olduğunda kullanışlı dokümantasyon üreteçleri de içerir:

  • markdown: Markdown dosyaları içeren bir klasör üretir.
  • html2: Tek ve bağımsız bir HTML sayfası üretir.

Java'yı kendiniz kurmadan npm sarmalayıcısı aracılığıyla çalıştırabilirsiniz:

npm install -g @openapitools/openapi-generator-cli

# Markdown dokümanları üret
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/

# Bağımsız HTML üret
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
Enter fullscreen mode Exit fullscreen mode

Npm sarmalayıcısı arka planda JDK destekli bir jar indirir. Bu nedenle ilk çalıştırma Widdershins'ten daha ağırdır; sonraki çalıştırmalar ise tek komutluk üretimdir.

En iyi kullanım: SDK üretimi için zaten kullandığınız aracı, doküman üretmek için de yeniden kullanmak.

Sınırlar: Çıktı basit ve şablon tabanlıdır. İlk çağrıda bir jar indirildiği için gerçek anlamda tek ikili dosya değildir. Sadece dokümantasyon istiyorsanız daha hafif seçenekler vardır.

Redocly CLI (build-docs)

Tek bir komutla iyi görünümlü ve bağımsız bir HTML sayfası istiyorsanız, Redocly CLI en kısa yoldur. build-docs komutu, belirtiminizi Redoc üzerine kurulu tek bir HTML dosyasına paketler.

npx @redocly/cli build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Varsayılan olarak redoc-static.html dosyasını üretir. Çıktı dosyasının adını --output ile değiştirin:

npx @redocly/cli build-docs openapi.yaml --output api.html
Enter fullscreen mode Exit fullscreen mode

Bunu CI içinde doğrudan kullanabilirsiniz:

- name: API dokümanlarını üret
  run: npx @redocly/cli build-docs openapi.yaml --output public/api.html
Enter fullscreen mode Exit fullscreen mode

npx ile çalıştığı için denemek amacıyla global kurulum yapmanız gerekmez.

En iyi kullanım: Temiz varsayılan temaya sahip, tek komutla oluşturulan ve paylaşılabilir tek sayfalık API referansı.

Sınırlar: Çıktı tek HTML dosyasıdır; çok sayfalı doküman portalından çok bir referans sayfasıdır. Daha zengin tema ve önizleme seçenekleri Redocly'nin ücretli katmanlarında bulunur. Benzer işleyicileri karşılaştırmak için Redocly alternatifleri ve Scalar alternatifleri yazılarına bakabilirsiniz.

Slate

Slate biraz farklıdır: Belirtimden dokümana dönüştürücü değildir; el yazısı API dokümanları için bir statik site üretecidir. Markdown yazarsınız, Slate ise klasik üç sütunlu doküman düzenini — navigasyon, içerik ve kod örnekleri — bağımsız statik siteye dönüştürür.

Middleman tarafından desteklendiği için Ruby gerekir.

# Slate deposunu klonladıktan ve bağımlılıkları kurduktan sonra
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

Bu komut, herhangi bir yerde barındırabileceğiniz build/ klasörüne eksiksiz bir statik site yazar.

Widdershins ile birlikte kullanmak için:

# 1. OpenAPI belirtiminden Markdown üret
widdershins openapi.yaml -o source/index.html.md

# 2. Slate sitesini oluştur
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

Bu akışla Slate düzeni içinde belirtim odaklı içerik elde edersiniz.

En iyi kullanım: Yapı ve nesir üzerinde editoryal kontrol istediğiniz, el yapımı ve anlatımsal API dokümanları.

Sınırlar: Ruby araç zinciri gerektirdiği için bu listedeki daha ağır seçeneklerden biridir. OpenAPI'yi doğrudan okumaz; Markdown sağlamanız gerekir. Dokümanlarınız tamamen belirtimden üretiliyorsa ve nadiren elle düzenleniyorsa, tek başına dönüştürücü daha hafiftir.

Apidog CLI (export ve doc)

Yukarıdaki açık araçların her biri tek bir dilimi kapsar: dönüştürme, işleme veya barındırma. API'niz tek bir YAML dosyası yerine zaten bir projede yaşıyorsa, bunları bir araya getirmek sürtüşme yaratabilir.

apidog-cli, Apidog'un komut satırı aracıdır. Tek bir dışa aktarma komutuyla projeyi, ayrı derleme ardışık düzeni kurmadan Markdown veya HTML'ye dönüştürür.

Npm'den kurun ve jetonla kimlik doğrulayın:

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Ardından proje dokümantasyonunu Markdown veya HTML olarak dışa aktarın:

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

CLI, doküman kaynaklarını doğrudan yönetmek için de komutlar sağlar:

# Projedeki Markdown dokümanlarını listele
apidog doc list --project <projectId>

# Yayınlanmış dokümantasyon sitelerini listele
apidog docs-site list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

Çıktı yapılandırılmış JSON'dur. Bu sayede sonucu başka adımlara aktarabilir veya bir CI betiğinde işleyebilirsiniz.

Tam komut yüzeyi için Apidog CLI tam kılavuzu, kimlik doğrulama, projeler ve komut gruplarını ayrıntılı olarak açıklar.

Dürüst çerçeve: Apidog açık kaynak değildir ve tek amaçlı bir ikili dosya değildir; CLI barındırılan bir projeyle konuşan freemium bir platformun parçasıdır. Ayrıca OpenAPI belirtiminizi denetlemez veya stil kılavuzu uygulamaz; Redocly ve Spectral bu kullanım alanına odaklanır.

CLI'ın sağladığı değer, dönüştürücü, işleyici ve ana bilgisayarı elle zincirlemek yerine, bakımı yapılan bir API projesinden paylaşılabilir Markdown veya HTML'ye entegre bir yol sunmasıdır. Özellikle Markdown dışa aktarma akışı için API doküman üreteci ile Markdown dışa aktarma yazısı daha ayrıntılıdır.

Nasıl seçilir?

Aracı, girdinizin biçimine ve ihtiyacınız olan çıktıya göre seçin.

Araç En iyisi Kurulum Açık kaynak mı? Çıktı
Widdershins Belirtimden hızlı Markdown üretimi npm i -g widdershins Evet (MIT) Markdown
OpenAPI Generator SDK'larla birlikte doküman üretimi npm i -g @openapitools/openapi-generator-cli Evet (Apache 2.0) Markdown veya HTML
Redocly CLI Tek ve gösterişli HTML sayfası npx @redocly/cli Evet (MIT, açık çekirdek) Bağımsız HTML
Slate Elle derlenmiş doküman sitesi Ruby + Bundler Evet (Apache 2.0) Statik site
Apidog CLI Canlı projeden dışa aktarma npm i -g apidog-cli Hayır (ücretsiz katman) Markdown veya HTML

Kısa karar rehberi:

  • Çıplak OpenAPI belirtiminiz varsa ve taahhüt edilecek Markdown istiyorsanız Widdershins kullanın.
  • Tek bir paylaşılabilir HTML sayfası istiyorsanız redocly build-docs en hızlı seçenektir.
  • Dokümanları elle yazıyor ve düzen üzerinde kontrol istiyorsanız Slate kullanın.
  • API'niz zaten bir projede yaşıyorsa ve tek CLI ile dışa aktarma ile doküman yönetimi istiyorsanız Apidog CLI kullanın.

Genel ücretsiz seçenekler için ücretsiz API dokümantasyon araçları derlemesi daha geniş bir görünüm sunar.

Özet

Hafif dokümantasyon araçları tek bir kurala dayanır: İhtiyacınız olan çıktıyı üreten en küçük aracı seçin.

  • Widdershins, belirtimden Markdown üretmek için en doğrudan seçenektir.
  • redocly build-docs, tek komutla bağımsız HTML referansı oluşturur.
  • OpenAPI Generator, zaten SDK üretiyorsanız mantıklıdır.
  • Slate, yalnızca dokümanları elle yazıyor ve daha kontrollü bir site düzeni istiyorsanız ek ayak izini hak eder.
  • API'niz tek dosya yerine gerçek bir projede yaşıyorsa, apidog-cli ek ardışık düzen kurmadan Markdown veya HTML dışa aktarır.

Son durum sizseniz, Apidog'u indirin ve bir projeye karşı apidog export komutunu deneyin. API değiştiğinde dokümanları yeniden oluşturmak için komutu CI görevinize ekleyebilirsiniz.

Top comments (0)