Ücretsiz Açık Kaynak CLI Araçları: API Dokümantasyonu

API belgelerinizi oluşturmak için bir araç seçtiğinizde, lisans kararın bir parçasıdır. Açık kaynaklı bir üretici, kodu okuyabileceğiniz, çıktıyı kendi sunucularınızda barındırabileceğiniz, takılıp kalırsa çatallayabileceğiniz ve halihazırda kullandığınız bir özellik için asla koltuk sınırına veya ödeme duvarına takılmayacağınız anlamına gelir. Her CI yapısında çalışan bir iş için bu, çıktı kalitesi kadar önemlidir. Bu liste, komut satırından çalışan API dokümantasyon araçlarının açık kaynaklı kesimidir. Buradaki her araç, MIT veya Apache 2.0 gibi gerçek bir lisans altında kaynak kodu mevcut, GitHub'da barındırılıyor ve hesap gerektirmeden çalıştırılabiliyor. Bir OpenAPI veya Swagger dosyasına işaret edersiniz ve size Markdown, statik bir HTML sayfası veya tamamen size ait ve kendi sunucularınızda barındırdığınız eksiksiz bir doküman sitesi sunar. Her biri için tam lisansı ve kendi kendine barındırma hikayesini belirteceğim, çünkü genel bir derleme yerine açık kaynaklı bir derleme okumanızın tüm nedeni budur. Daha geniş alanı merak ediyorsanız, [en iyi REST API dokümantasyon araçları](https://apidog.com/tr/blog/top-10-rest-api-documentation-tools) derlemesi GUI platformlarını da kapsar. [OpenAPI Spesifikasyonu](https://spec.openapis.org/oas/latest.html) aşağıdaki her aracın okuduğu formattır, bu yüzden geçerli bir spesifikasyon başlangıç noktanızdır. Baştan dürüst bir not. [Apidog](https://apidog.com) sona doğru görünüyor ve açık kaynaklı bir giriş değil; ticari bir freemium platformu. Açık kaynak araçların bir boşluk bıraktığı durumlar için sadece etiketli bir not olarak dahil ettim ve bu çizgi hakkında açık olacağım.button

Bir CLI dokümantasyon aracını "açık kaynak" yapan nedir

Açık kaynak sadece "indirmesi ücretsiz" değildir. Bir yapıya bağlayacağınız dokümantasyon araçları için, bir aracın gerçekten size ait olup olmadığını üç şey belirler.

Gerçek bir lisans. MIT veya Apache 2.0, aracı ticari olarak izin almadan kullanabileceğiniz, değiştirebileceğiniz ve yeniden dağıtabileceğiniz anlamına gelir. Her ikisi de OSI onaylıdır. Apache 2.0, bazı hukuk ekiplerinin tercih ettiği açık bir patent hakkı ekler. Aşağıdaki her araç bu ikisinden birini taşır.

Kendi kendine barındırılabilir çıktı. Açık dokümanların amacı, hiçbir şeyin bir satıcının sunucularına bağlı olmamasıdır. Bu araçlar statik dosyalar yazar: taahhüt ettiğiniz Markdown, tek bir HTML sayfası veya bir HTML/CSS/JS klasörü. Bunu GitHub Pages, S3 veya basit bir Nginx kutusunda barındırırsınız ve aracın arkasındaki proje çalışsın ya da çalışmasın çalışmaya devam eder.

Bakım ve topluluk. Kaynak kodu mevcut olmak, ancak kod canlıysa işe yarar. Yıldızlar, son taahhütler ve açık sorunlar, bir çatallamanın gerçekten ihtiyaç duyduğunuzda uygulanabilir olup olmadığını size söyler. Buradaki birkaç araç arşivlenmiş olsa da hala çalışıyor; bunu belirteceğim.

Hem açık hem de freemium seçeneklerinde maliyetsiz açıdan, [ücretsiz API dokümantasyon araçları](https://apidog.com/tr/blog/api-documentation-free-tools) listesi eşlik eden parçadır. Şimdi araçlar.

Redocly CLI

Redocly CLI, bir spesifikasyonu düzenli, bağımsız bir HTML referansına dönüştürmenin en hızlı yoludur. MIT lisanslı ve açık çekirdektir: CLI ve altındaki Redoc oluşturma motoru GitHub'da açık kaynaktır, bazı barındırılan portal özellikleri ise Redocly'nin ücretli ürünlerinde bulunur. build-docs komutu tamamen açık kaynaklı yarıdadır.

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

Bu, Redoc üzerine kurulu bir HTML dosyası yazar. Yerel olarak açın, herhangi bir statik ana bilgisayara bırakın veya bir sürüme ekleyin. Hiçbir şey eve telefon etmez ve paket önbelleğe alındıktan sonra çevrimdışı çalıştırabilirsiniz.

En iyi olduğu durumlar: tek bir komutla temiz, tek sayfalık bir API referansı, MIT lisanslı ve kendi sunucusunda barındırılan. Dürüst sınırlamalar: çıktı tek bir sayfadır, bu nedenle çok sayfalı bir portal yerine bir referanstır ve daha zengin temalandırma ücretli katmanda yer alır. Oluşturma motorlarını birbiriyle karşılaştırıyorsanız, [Redocly alternatifleri](https://apidog.com/tr/blog/redocly-alternatives) karşılaştırması açık kaynak sınırının nerede bittiğini ortaya koyar.

Widdershins

Widdershins, MIT lisansı altında saf bir dönüştürücüdür. OpenAPI 3, Swagger 2 veya AsyncAPI okur ve Markdown yayar; tüm iş bu kadardır. Çıktı düz Markdown olduğu için, tamamen size aittir: taahhüt edin, bir pull request'te farkını görün veya zaten çalıştırdığınız herhangi bir statik siteye besleyin.

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

Yazdığı Markdown, Slate uyumludur, bu da onu bu listenin ilerleyen kısımlarındaki site oluşturucularla düzgün bir şekilde eşleştirir. Kullanışlı bayraklar: --omitHeader ön bilgiyi düşürür ve --language_tabs kod örneği dillerini seçer.

En iyi olduğu durumlar: sıfır kilitlenmeyle spesifikasyon içeriğini sürüm kontrol edilebilir Markdown'a almak. Dürüst sınırlamalar: sadece Markdown elde edersiniz. Stil yok ve oluşturulmuş site yok, bu yüzden Widdershins bir işlem hattının yarısıdır; başka bir şey Markdown'ı sayfalara dönüştürür.

OpenAPI Generator

OpenAPI Generator, Apache 2.0 lisanslı ve topluluk tarafından işletilen, 2018'de Swagger Codegen'dan çatallanmıştır. En çok istemci SDK'ları ile bilinir, ancak dokümantasyon oluşturucuları da içerir: markdown oluşturucu bir Markdown klasörü yazar ve html2 tek, bağımsız bir HTML sayfası yazar.

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/

Apache 2.0 lisansı ve patent hakkı, temkinli hukuk ekipleri için kolay bir onay sağlar ve proje bu alandaki en aktif şekilde bakımı yapılan projelerden biridir.

En iyi olduğu durumlar: hem SDK'lar hem de dokümanlar için tek bir aracı güçlü topluluk desteğiyle izin veren bir lisans altında yeniden kullanmak. Dürüst sınırlamalar: npm sarmalayıcısı ilk çalıştırmada hala bir Java jar indirir, bu yüzden tek bir ikili değildir ve şablonlu çıktı basittir. Yalnızca dokümanlara ihtiyacınız varsa, daha hafif dönüştürücüler mevcuttur.

Swagger Codegen

Swagger Codegen, Swagger ekibinden orijinal şablon tabanlı oluşturucudur, Apache 2.0 lisansı altındadır. OpenAPI Generator çatallanmasından önce gelir ve hala SmartBear tarafından bakımı yapılır. Dokümanlar için iki yol sunar: statik tek sayfalık bir referans için html ve küçük etkileşimli bir site için dynamic-html.

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/

İki proje DNA'yı ve birçok seçeneği paylaşır, bu nedenle ekibiniz zaten Swagger araç zincirinde standartlaşmışsa, bu sizi içinde tutar.

En iyi olduğu durumlar: Swagger ekosistemine zaten yatırım yapmış ve taslaklarını oluşturan Apache 2.0 aracıyla aynı dokümanları isteyen ekipler. Dürüst sınırlamalar: OpenAPI Generator gibi Java desteklidir ve geliştirme topluluk çatallanmasından daha yavaştır. Çoğu yeni kurulum için OpenAPI Generator daha aktif bir seçimdir; Swagger Codegen süreklilik konusunda kazanır.

OpenAPI eklentisi ile Docusaurus

Tek bir HTML sayfası yeterli değilse ve gerçek, sürümlü bir dokümantasyon sitesi istiyorsanız, [Docusaurus](https://github.com/facebook/docusaurus) açık kaynaklı temeldir. MIT lisanslıdır, Meta tarafından geliştirilmiştir ve web'deki en yaygın kullanılan statik site oluşturuculardan biridir. Kendi başına Markdown ve MDX'i işler; yine MIT lisanslı ve Palo Alto Networks tarafından bakımı yapılan [docusaurus-openapi-docs](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs) eklentisi, spesifikasyondan dokümanlara oluşturmayı ekler.

npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all

Eklentiyi spesifikasyon yolunuzla yapılandırdıktan sonra, gen-api-docs OpenAPI dosyasını Docusaurus sitesinde işlenen MDX sayfalarına dönüştürür, eksiksiz bir "deneme" paneli ve kenar çubuğu navigasyonu ile.

En iyi olduğu durumlar: oluşturulmuş referansın yanı sıra sürümlendirme, arama ve elle yazılmış kılavuzlarla dolu, tamamen kendi kendine barındırılan eksiksiz bir doküman portalı. Dürüst sınırlamalar: buradaki en ağır kurulumdur. Bir React sitesi ve bir yapı adımı kuruyorsunuz, bu yüzden tek ihtiyacınız bir referans sayfasıysa gereksizdir. Bunun için Redocly CLI daha kısa yoldur.

Slate

Slate, klasik üç sütunlu API doküman düzenidir: solda navigasyon, ortada düz metin, sağda kod örnekleri, hepsi statik bir site olarak oluşturulur. Apache 2.0 lisanslıdır ve Middleman tarafından desteklenir, bu yüzden bir Ruby araç zincirine ihtiyaç duyar. Yukarıdaki dönüştürücülerin aksine, Slate OpenAPI'yi doğrudan okumaz; Markdown yazarsınız ve Slate onu oluşturur.

# Slate çatallamanızı klonladıktan ve bundle install çalıştırdıktan sonra
bundle exec middleman build

Bu, istediğiniz yere barındırabileceğiniz bir build/ klasörüne eksiksiz bir statik site yazar. Widdershins'in faydası burada ortaya çıkar: spesifikasyonunuzu Markdown'a dönüştürün, ardından Slate'in onu tanınabilir düzende oluşturmasına izin verin.

En iyi olduğu durumlar: tamamen kendi kendine barındırılan statik bir sitede yapı ve düz metin üzerinde editoryal kontrole sahip olmak istediğiniz, elle düzenlenmiş, anlatısal dokümanlar. Dürüst sınırlamalar: orijinal depo arşivlenmiş olsa da (bakımcı geri çekildi), hala oluşturuluyor ve çatallamalar aktif, ve Ruby bağımlılığı bir npx tek satırlık komutundan daha ağırdır. Dokümanlarınız doğrudan bir spesifikasyondan yeniden oluşturuluyorsa, bir dönüştürücü daha hafiftir.

Apidog CLI (dürüst bir not, açık kaynak bir giriş değildir)

Yukarıdaki araçların hepsi açık kaynaktır ve her biri bir dilimi kapsar: statik bir dosyayı dönüştürmek, oluşturmak veya barındırmak. Bıraktıkları boşluk ise canlı bir projedir. API'niz tek başına bir YAML dosyası değil, uç noktaları, şemaları ve örnekleri olan bakımı yapılan bir proje ise, bir dönüştürücüyü, bir oluşturucuyu ve bir ana bilgisayarı elle birbirine zincirlemeye ve üçünü de senkronize tutmaya başlarsınız.

İşte bu boşluğu apidog-cli ikili dosyası doldurur. Lisans konusunda açık olmak gerekirse: Apidog açık kaynak değildir. Ücretsiz bir katmanı olan ticari bir freemium platformudur ve CLI yerel bir spesifikasyon yerine barındırılan bir projeyle konuşur. Bunu buraya dahil etmemin tek nedeni, karşılaştırmanın açık kaynak araçların neyi kapsayıp neyi kapsamadığı konusunda dürüst olmasıdır, açık kaynak bir seçenek olarak değil.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html

Tek bir dışa aktarma, projeyi bir derleme hattı olmadan Markdown veya HTML'ye dönüştürür ve apidog doc ve apidog docs-site, bir betikten doküman kaynaklarını yönetir. Çıktı yapılandırılmış JSON'dur, bu nedenle CI veya bir aracıya temiz bir şekilde aktarılır. [Apidog CLI kapsamlı rehberi](https://apidog.com/tr/blog/apidog-cli-complete-guide) kimlik doğrulamayı ve her komut grubunu anlatır. Markdown dışa aktarma iş akışı aradığınız şeyse, [Markdown dışa aktarmalı API doküman oluşturucu](https://apidog.com/tr/blog/api-doc-generator-markdown-export) yazısı daha derine iner.

Sınırın nerede oturduğu: açık kaynak araçlar size sahip olduğunuz kodu, kendi sunucularınızda barındırdığınız dosyaları ve satıcı bağımlılığı olmadan verir. Apidog, bakımı yapılan bir projeden paylaşılabilir dokümanlara tek bir entegre yol sunar, ancak bunun bedeli barındırılan bir freemium ürün olmasıdır. Doğruluk kaynağınızın statik bir spesifikasyon mu yoksa canlı bir proje mi olduğuna göre seçim yapın.

Nasıl seçilir

Lisansı ve çıktıyı ekibinizin sahip olması gerekenlere göre eşleştirin.

Kısa versiyon: Yalın bir spesifikasyon ve paylaşılabilir bir HTML referansı için Redocly CLI kullanın. Sürüm kontrolü yaptığınız Markdown için Widdershins. Zaten SDK'lar oluşturuyorsanız, OpenAPI Generator da dokümanları yapar ve Swagger'da standartlaşmışsanız Swagger Codegen size yardımcı olur. Sürümlendirme ve kılavuzlarla gerçek bir portal istediğinizde, Docusaurus ve OpenAPI eklentisi açık kaynaklı temeldir ve Slate, elle yazılmış, editoryal olarak kontrol edilen dokümanlar için seçenektir. Bunların her biri kaynak kodu mevcuttur ve kendi kendine barındırılabilir, bu nedenle yayınladığınız hiçbir şey bir satıcının iş hayatında kalmasına bağlı değildir. Daha geniş maliyetsiz bakış açısı için, [ücretsiz API dokümantasyon araçları](https://apidog.com/tr/blog/free-api-documentation-tools) derlemesi hem açık hem de freemium seçeneklerini bir araya getirir.

Özetliyor

Açık kaynaklı bir dokümantasyon CLI seçimi lisansa, çıktıya ve dokümanlarınızın nerede yaşadığına bağlıdır. MIT ve Apache 2.0, koltuk maliyeti olmadan kullanmanıza, değiştirmenize ve kendi sunucunuzda barındırmanıza olanak tanır, bu nedenle ihtiyacınız olan çıktıyı üreten en küçük aracı seçin: bir sayfa için Redocly CLI, Markdown için Widdershins, SDK'larınızın yanında dokümanlar için OpenAPI Generator veya Swagger Codegen, bir portal için Docusaurus, elle düzenlenmiş sayfalar için Slate.

API'niz tek bir dosya yerine bakımı yapılan bir projede yaşıyorsa ve üç aracı zincirlemek yerine dokümanları dışa aktarmayı tercih ediyorsanız, [Apidog'u indirin](https://apidog.com/download) ve bir projeye karşı apidog export'u deneyin. Bir CI işine düşer, böylece API her değiştiğinde dokümanlarınız yeniden oluşturulur, ancak bunun açık kaynaklı bir ikili değil, freemium bir platform olduğunu açıkça anlayın.