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.

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, ki 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, 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, bir dil çalışma zamanı artı bir paketleyici artı bir eklenti sistemi kurmak anlamına geliyorsa, çıktı neye benzerse benzesin bu hafif değildir.

Başlangıç ve yapılandırma. Bunların en iyileri, 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. Çalışmadan önce bir yapılandırma dosyasına ihtiyaç duyan her şey burada puan kaybeder.

Tek amaçlı çıktı. Aşağıdaki her araç tek bir şey yapar: belirtim içeri, dokümanlar dışarı. Markdown veya HTML, başka hiçbir şey ekli değildir. Bu, onları bir ardışık düzende hızlı ve tahmin edilebilir tutar.

Her yerde çalışır. GUI yok, açık araçlar için giriş yok, canlı tutulacak sunucu yok. Dizüstü bilgisayarınızda çalışır ve bir CI görevinde de aynı şekilde çalışır. Daha geniş bir ücretsiz seçenekler yelpazesi için, ücretsiz API dokümantasyon araçları listesinde platformlar bulunur; bu, bunun CLI dilimidir.

Ş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. İşin tamamı budur. Bir site oluşturmaz veya bir sunucu çalıştırmaz; size bir .md dosyası verir ve aradan çekilir.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

Ürettiği Markdown, daha sonra statik bir siteye beslemeyi planlıyorsanız önemli olan Slate uyumludur. Kullanışlı bayraklar: --omitHeader YAML ön bilgilerini atar ve --language_tabs hangi kod örnekleme dillerinin gösterileceğini kontrol eder.

En iyisi: belirtim içeriğini taahhüt edebileceğiniz, karşılaştırabileceğiniz ve herhangi bir doküman sistemine bırakabileceğiniz Markdown'a aktarmak. Dürüst sınırlar: sadece Markdown alırsınız. Stil yok, etkileşimli "deneyin" paneli yok ve barındırılan çıktı yok. Widdershins bir dönüştürücüdür, bir işleyici değil, bu yüzden onu Markdown'ı bir siteye dönüştüren bir şeyle eşleştirirsiniz.

OpenAPI Generator (doküman üreteçleri)

OpenAPI Generator en çok istemci SDK'ları ile bilinir, ancak aynı zamanda dokümantasyon üreteçleri de içerir ve bunlar sadece bir belirtiminiz olduğunda kullanışlıdır. markdown üreteci bir Markdown klasörü yazar; html2 üreteci tek bir bağımsız HTML sayfası yazar. Java'yı kendiniz kurmadan npm sarmalayıcısı aracılığıyla çalıştırabilirsiniz.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/

Npm sarmalayıcısı yine de arka planda bir JDK destekli jar indirir, bu yüzden ilk çalıştırmada Widdershins'ten daha ağırdır. Ondan sonra tek komutluk bir üretmedir.

En iyisi: SDK'lar için zaten çalıştırıyor olabileceğiniz bir aracı, hem Markdown hem de bağımsız HTML seçeneğiyle dokümanlar çıkarmak için yeniden kullanmak. Dürüst sınırlar: çıktı basit ve şablon tabanlıdır ve ilk çağrı bir jar çeker, bu yüzden gerçekten tek bir ikili dosya değildir. Sadece dokümanlara ihtiyacınız varsa, daha hafif seçenekler mevcuttur.

Redocly CLI (build-docs)

Tek bir komutla iyi görünümlü, bağımsız bir HTML sayfası istiyorsanız, Redocly CLI en kısa yoldur. build-docs komutu, belirtiminizi Redoc üzerine kurulu tek bir bağımsız HTML dosyasına paketler. Sunucu yok, ayrı barındırma derlemesi yok; açabileceğiniz, e-posta gönderebileceğiniz veya herhangi bir statik ana bilgisayara bırakabileceğiniz bir dosya alırsınız.

npx @redocly/cli build-docs openapi.yaml

Varsayılan olarak redoc-static.html yazar. Adı --output ile değiştirin:

npx @redocly/cli build-docs openapi.yaml --output api.html

npx aracılığıyla çalıştığı için, denemek için global olarak yüklemenize bile gerek yoktur. En iyisi: tek bir komutla gösterişli tek sayfalık bir referans, temiz bir varsayılan tema ve yönetilecek bir barındırma hikayesi olmadan. Dürüst sınırlar: çıktı tek bir HTML dosyasıdır, bu yüzden çok sayfalı bir doküman portalından ziyade bir referans sayfasıdır ve daha zengin temalandırma ve önizlemeler Redocly'nin ücretli katmanlarında bulunur. Benzer işleyicilerle karşılaştırıyorsanız, Redocly alternatifleri ve Scalar alternatifleri karşılaştırmaları, takasları ortaya koyar.

Slate

Slate burada biraz farklıdır: bir belirtimden dokümanlara dönüştürücü değildir, el yazısı API dokümanları için bir statik site üretecidir. Markdown yazarsınız ve Slate, klasik üç sütunlu doküman düzenini (navigasyon, içerik ve kod örnekleri yan yana) bağımsız bir statik siteye dönüştürür. Middleman tarafından desteklenir, bu yüzden Ruby'ye ihtiyaç duyar.

# slate deposunu klonladıktan ve bağımlılıkları kurduktan sonra
bundle exec middleman build

Bu, herhangi bir yerde barındırabileceğiniz build/ klasörüne eksiksiz bir statik site yazar. Widdershins'in işe yaradığı yer burasıdır: belirtiminizden Markdown oluşturun, sonra Slate'in onu işlemesine izin verin ve Slate'in düzeninde belirtim odaklı içerik elde edersiniz.

En iyisi: Yapı ve nesir üzerinde editoryal kontrol istediğiniz, el yapımı, anlatımsal API dokümanları. Dürüst sınırlar: bir Ruby araç zincirine ihtiyaç duyduğu için bu listedeki en ağır seçenektir ve OpenAPI'yi kendi başına okumaz; ona Markdown beslersiniz. Dokümanlarınız doğrudan bir belirtimden üretiliyorsa ve nadiren elle düzenleniyorsa, tek başına bir dönüştürücü daha hafiftir.

Apidog CLI (export + 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üşmedir. apidog-cli ikilisi işte buraya uyar. Apidog'un komut satırı arkadaşıdır ve tek bir dışa aktarma, bir projeyi bir derleme ardışık düzeni olmadan Markdown veya HTML'ye dönüştürür.

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

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>

Ardından projenin dokümantasyonunu tek bir komutla Markdown veya HTML'ye aktarın:

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

CLI ayrıca doküman kaynaklarını doğrudan yönetir. apidog doc projenin Markdown dokümanlarını işler ve apidog docs-site yayınlanmış dokümantasyon sitelerini yönetir, böylece bir betik veya CI işinden dokümanları listeleyebilir, oluşturabilir ve güncelleyebilirsiniz:

apidog doc list --project <projectId>
apidog docs-site list --project <projectId>

Çıktı yapılandırılmış JSON'dur, bu da diğer adımlara aktarmayı veya bir aracıya vermeyi kolaylaştırır. Tam komut yüzeyi için, Apidog CLI tam kılavuzu, kimlik doğrulama, projeler ve her komut grubunu ayrıntılı olarak açıklar.

İşte dürüst çerçeve. Apidog açık kaynak değildir ve tek amaçlı bir ikili dosya değildir; bir freemium platformudur ve CLI, barındırılan bir projeyle konuşur. Ayrıca OpenAPI'nizi denetlemez veya bir stil kılavuzunu uygulamaz; Redocly ve Spectral bunu yapar. CLI'ın size verdiği şey, bir dönüştürücü, bir işleyici ve bir ana bilgisayarı elle zincirlemek yerine, bakımı yapılan bir API projesinden paylaşılabilir Markdown veya HTML'ye tek bir entegre yoldur. Özellikle markdown-export yolunu istiyorsanız, API doküman üreteci ile Markdown dışa aktarma parçası bu iş akışını daha derinlemesine inceler.

Nasıl seçilir

Aracı, girdinizin şekline ve ihtiyacınız olan çıktıya göre eşleştirin.

Kısa versiyonu: Çıplak bir 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ısıdır. Dokümanları elle yazıyorsanız ve düzgün bir düzen istiyorsanız, Slate. Ve API'niz zaten bir projede yaşıyorsa ve tek bir CLI'da dışa aktarma ve doküman yönetimi istiyorsanız, Apidog. Genel olarak ücretsiz bir genel bakış için, ücretsiz API dokümantasyon araçları derlemesi hepsini bir araya getiriyor.

Özetliyor

Hafif dokümantasyon araçları tek bir kurala dayanır: ihtiyacınız olan çıktıyı üreten en küçük şeyi seçin. Widdershins ve redocly build-docs, çoğu belirtimden dokümanlara durumunu tek bir komutla kapsar. OpenAPI Generator, zaten SDK'lar üretiyorsanız değerlidir. Slate, daha ağır ayak izini yalnızca dokümanları elle yazıyorsanız hak eder. Ve API'niz tek bir dosya yerine gerçek bir projede yaşıyorsa, apidog-cli dışa aktarma, bir ardışık düzen olmadan size Markdown veya HTML verir.

Son durum sizseniz, Apidog'u indirin ve bir projeye karşı apidog export komutunu deneyin; API her değiştiğinde dokümanlarınızın yeniden oluşturulması için bir CI görevine sorunsuz bir şekilde düşer.