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

API belgelerinizi oluşturmak için bir araç seçerken lisans da teknik bir karardır. Açık kaynaklı bir üreticiyle kodu inceleyebilir, çıktıyı kendi sunucularınızda barındırabilir, gerektiğinde projeyi çatallayabilir ve kullandığınız özellikler için koltuk sınırı veya ödeme duvarıyla karşılaşmazsınız. Bu, her CI çalıştırmasında doküman üreten ekipler için çıktı kalitesi kadar önemlidir. Bu rehberde, komut satırından çalışan açık kaynaklı API dokümantasyon araçlarını uygulama odaklı olarak karşılaştıracağım. Her araç OpenAPI veya Swagger dosyasını Markdown, statik HTML ya da tamamen sizin yönettiğiniz bir dokümantasyon sitesine dönüştürür. Daha geniş bir araç listesi için en iyi REST API dokümantasyon araçları derlemesine de bakabilirsiniz. Tüm araçların temel girdisi OpenAPI Spesifikasyonu olduğundan, başlangıçta geçerli bir spesifikasyona ihtiyacınız vardır. Ayrıca, sona doğru yer alan Apidog açık kaynaklı değildir; bunu açık kaynak araçların kapsamadığı senaryolar için etiketli bir karşılaştırma notu olarak ele alacağım.

Apidog'u bugün deneyin

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

Bir aracın ücretsiz olması, açık kaynak olduğu anlamına gelmez. CI hattınıza ekleyeceğiniz bir API dokümantasyon aracı için şu üç noktayı doğrulayın:

1. Gerçek bir açık kaynak lisansı
   
   MIT veya Apache 2.0 gibi lisanslar; aracı ticari olarak kullanmanıza, değiştirmenize ve yeniden dağıtmanıza izin verir. Apache 2.0 ayrıca açık bir patent hakkı içerir.

2. Kendi kendine barındırılabilir çıktı
   
   Araç Markdown, tek bir HTML dosyası veya HTML/CSS/JS klasörü üretmelidir. Böylece çıktıyı GitHub Pages, S3 veya Nginx üzerinde yayınlayabilirsiniz.

3. Aktif bakım ve topluluk
   
   Depodaki son taahhütleri, açık sorunları ve sürüm geçmişini kontrol edin. Arşivlenmiş projeler çalışmaya devam edebilir, ancak uzun vadeli bakım yükü size kalabilir.

Açık kaynak ve freemium seçenekleri birlikte değerlendirmek için ücretsiz API dokümantasyon araçları listesini de inceleyebilirsiniz.

Redocly CLI

Redocly CLI, bir OpenAPI spesifikasyonunu hızlıca bağımsız bir HTML API referansına dönüştürmek için kullanılır. MIT lisanslıdır. CLI ve Redoc oluşturma motoru açık kaynaklıdır; bazı barındırılan portal özellikleri ise ücretli Redocly ürünlerinde bulunur.

Hızlı başlangıç

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

Komut tamamlandığında api-docs.html dosyasını yerelde açabilir veya doğrudan statik sunucunuza yükleyebilirsiniz.

CI içinde örnek kullanım:

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

Bu dosyayı sürüm çıktınıza ekleyebilir ya da public/ klasörünü GitHub Pages benzeri bir ortama dağıtabilirsiniz.

Ne zaman seçilmeli?

• Tek komutla temiz bir API referansı üretmek istiyorsanız
• Çıktınız tek bir HTML dosyası olmalıysa
• MIT lisansı ve kendi kendine barındırma sizin için önemliyse

Sınırlamalar

• Çıktı tek sayfalıdır.
• Zengin tema ve portal özelliklerinin bir bölümü ücretli katmandadır.

Oluşturma araçlarını karşılaştırıyorsanız, Redocly alternatifleri karşılaştırmasına bakabilirsiniz.

Widdershins

Widdershins, OpenAPI 3, Swagger 2 veya AsyncAPI tanımlarını Markdown'a dönüştüren MIT lisanslı bir dönüştürücüdür. Çıktı düz Markdown olduğundan, dosyayı Git'e ekleyebilir, pull request içinde farklarını inceleyebilir ve mevcut statik site altyapınıza aktarabilirsiniz.

Hızlı başlangıç

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

Kod örneği dillerini seçmek veya varsayılan başlığı kaldırmak için bayrak kullanabilirsiniz:

widdershins openapi.yaml \
  --omitHeader \
  --language_tabs 'javascript:JavaScript' 'python:Python' \
  -o api-docs.md

Üretilen Markdown Slate uyumludur. Bu nedenle Widdershins'i Markdown üreten ilk adım, Slate veya başka bir site oluşturucuyu ise yayınlama adımı olarak kullanabilirsiniz.

Ne zaman seçilmeli?

• Spesifikasyonunuzu sürüm kontrol edilebilir Markdown'a dönüştürmek istiyorsanız
• Doküman görünümünü başka bir araçla oluşturacaksanız
• Minimum araç bağımlılığı istiyorsanız

Sınırlamalar

• Site veya tema üretmez.
• Markdown çıktısını HTML sayfalarına dönüştürmek için ek bir araç gerekir.

OpenAPI Generator

OpenAPI Generator, Apache 2.0 lisanslı ve topluluk tarafından sürdürülen bir projedir. 2018'de Swagger Codegen'dan çatallanmıştır. En çok istemci SDK üretimiyle bilinse de API dokümantasyonu için de oluşturucular sunar:

• markdown: Markdown klasörü üretir.
• html2: bağımsız bir HTML sayfası üretir.

Hızlı başlangıç

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/

Aynı OpenAPI dosyasından SDK ve dokümantasyon üretmek istiyorsanız, bunu CI hattınıza tek bir araç olarak ekleyebilirsiniz:

openapi-generator-cli generate -g typescript-fetch -i openapi.yaml -o sdk/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs/

Ne zaman seçilmeli?

• SDK'ları ve dokümantasyonu aynı OpenAPI tanımından üretmek istiyorsanız
• Apache 2.0 lisansı ve patent hakkı önemliyse
• Aktif topluluk desteği olan bir araç arıyorsanız

Sınırlamalar

• npm sarmalayıcısı ilk çalıştırmada Java JAR dosyası indirir.
• Yalnızca dokümantasyon ihtiyacınız varsa daha hafif dönüştürücüler tercih edilebilir.
• Varsayılan şablon çıktısı temel düzeydedir.

Swagger Codegen

Swagger Codegen, Swagger ekibinin orijinal şablon tabanlı oluşturucusudur ve Apache 2.0 lisansı altında yayınlanır. Hâlâ SmartBear tarafından sürdürülür.

Dokümantasyon için iki temel seçenek sunar:

• html: statik, tek sayfalık API referansı
• dynamic-html: küçük etkileşimli site

Hızlı başlangıç

npm install -g swagger-codegen-cli

swagger-codegen-cli generate \
  -i openapi.yaml \
  -l html \
  -o docs/

Ekibiniz hâlihazırda Swagger araç zincirini kullanıyorsa, mevcut iş akışını değiştirmeden dokümantasyon üretimi ekleyebilirsiniz.

Ne zaman seçilmeli?

• Swagger ekosisteminde standartlaşmışsanız
• Apache 2.0 lisanslı bir araç kullanmak istiyorsanız
• Mevcut Swagger Codegen şablonlarını veya süreçlerini korumanız gerekiyorsa

Sınırlamalar

• Java bağımlılığı vardır.
• Gelişim hızı OpenAPI Generator topluluğuna göre daha yavaştır.
• Yeni kurulumlarda OpenAPI Generator genellikle daha aktif bir seçenektir.

OpenAPI eklentisi ile Docusaurus

Tek bir HTML referansı yeterli değilse, sürümlendirme, arama, rehberler ve API referansını birlikte içeren bir dokümantasyon portalı kurabilirsiniz. Bu senaryoda Docusaurus açık kaynaklı temel olarak kullanılabilir.

Docusaurus MIT lisanslıdır. OpenAPI üretimi için yine MIT lisanslı, Palo Alto Networks tarafından sürdürülen docusaurus-openapi-docs eklentisini ekleyin.

Hızlı başlangıç

npx create-docusaurus@latest my-docs classic

cd my-docs

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs

npm run docusaurus gen-api-docs all

Eklenti yapılandırmasında OpenAPI dosyanızın yolunu belirtin. Ardından gen-api-docs, spesifikasyonu Docusaurus tarafından işlenen MDX sayfalarına dönüştürür. Böylece kenar çubuğu navigasyonu ve "deneme" paneli bulunan bir referans oluşturabilirsiniz.

Ne zaman seçilmeli?

• API referansının yanında kullanım kılavuzları da yayınlayacaksanız
• Sürümlenmiş, kendi kendine barındırılan bir doküman portalı istiyorsanız
• React tabanlı bir statik site iş akışı kullanıyorsanız

Sınırlamalar

• Bu listedeki en kapsamlı kurulumdur.
• React sitesi, eklenti yapılandırması ve build adımı gerektirir.
• Tek bir API referans sayfası için Redocly CLI daha kısa bir yol olabilir.

Slate

Slate, API dokümantasyonu için klasik üç sütunlu görünümü sunar:

• Solda navigasyon
• Ortada açıklamalar
• Sağda kod örnekleri

Apache 2.0 lisanslıdır ve Middleman ile çalışır. Slate OpenAPI dosyasını doğrudan okumaz; Markdown içeriğini statik siteye dönüştürür.

Hızlı başlangıç

Slate çatallamanızı klonladıktan ve bağımlılıkları kurduktan sonra:

bundle install
bundle exec middleman build

Komut, yayınlayabileceğiniz bir build/ klasörü üretir.

Widdershins ve Slate'i birlikte kullanmak için:

widdershins openapi.yaml -o source/includes/_api.md
bundle exec middleman build

Bu akışta Widdershins spesifikasyonu Markdown'a dönüştürür, Slate ise Markdown'ı tanınabilir üç sütunlu doküman sitesine çevirir.

Ne zaman seçilmeli?

• Doküman metni ve yapısı üzerinde editoryal kontrol istiyorsanız
• Üç sütunlu klasik API dokümantasyon görünümünü tercih ediyorsanız
• Tamamen kendi kendine barındırılan bir statik site yayınlayacaksanız

Sınırlamalar

• Orijinal depo arşivlenmiştir; proje hâlâ oluşturulabilir olsa da bakım durumunu değerlendirmelisiniz.
• Ruby ve Bundler gerektirir.
• Spesifikasyondan doğrudan yeniden üretim için tek başına yeterli değildir.

Apidog CLI: Açık kaynaklı bir giriş değildir

Yukarıdaki araçların tamamı açık kaynaklıdır. Ancak her biri iş akışının yalnızca bir bölümünü kapsar: dönüştürme, oluşturma veya barındırma.

API'niz yalnızca bir YAML dosyası değil; uç noktaları, şemaları ve örnekleri olan, aktif olarak sürdürülen bir projeyse dönüştürücü, site oluşturucu ve barındırma adımlarını ayrı ayrı senkronize etmeniz gerekir.

Bu noktada apidog-cli kullanılabilir. Ancak lisans sınırını net tutmak gerekir: Apidog açık kaynak değildir. Ücretsiz katmanı bulunan ticari bir freemium platformdur ve CLI, yerel bir spesifikasyon yerine barındırılan bir projeyle çalışır.

Dışa aktarma örneği

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

Bu komutlar projeyi Markdown veya HTML olarak dışa aktarır. apidog doc ve apidog docs-site komutlarıyla doküman kaynaklarını betik üzerinden de yönetebilirsiniz.

Kimlik doğrulama ve komut grupları için Apidog CLI kapsamlı rehberi inceleyin. Markdown çıktı odaklı kullanım için Markdown dışa aktarmalı API doküman oluşturucu yazısı daha ayrıntılıdır.

Açık kaynak araçlar; sahip olduğunuz kodu, kendi barındırdığınız dosyaları ve satıcı bağımlılığı olmayan bir yayın sürecini sunar. Apidog ise sürdürülen bir projeden paylaşılabilir dokümanlara entegre bir yol sunar, ancak barındırılan freemium bir ürün olma karşılığında.

Nasıl seçilir?

Lisansı, çıktıyı ve bakım modelini ekibinizin ihtiyacına göre eşleştirin.

Araç	En iyi olduğu durum	Kurulum	Açık kaynak mı?	Çıktı
Redocly CLI	Temiz tek sayfalık HTML referansı	npx @redocly/cli	Evet, MIT; açık çekirdek	Bağımsız HTML
Widdershins	Spesifikasyondan Markdown üretimi	npm i -g widdershins	Evet, MIT	Markdown
OpenAPI Generator	SDK ve dokümanları tek araçla üretme	npm i -g @openapitools/openapi-generator-cli	Evet, Apache 2.0	Markdown veya HTML
Swagger Codegen	Swagger araç zinciri kullanan ekipler	npm i -g swagger-codegen-cli	Evet, Apache 2.0	HTML
Docusaurus + OpenAPI eklentisi	Tam dokümantasyon portalı	npx create-docusaurus	Evet, MIT	Statik site
Slate	Elle düzenlenen üç sütunlu dokümanlar	Ruby + Bundler	Evet, Apache 2.0	Statik site
Apidog CLI	Canlı projeden doküman dışa aktarma	npm i -g apidog-cli	Hayır, freemium	Markdown veya HTML

Kısa karar rehberi:

• Tek HTML referansı: Redocly CLI
• Git'e eklenebilir Markdown: Widdershins
• SDK ve doküman üretimi: OpenAPI Generator
• Mevcut Swagger Codegen standardı: Swagger Codegen
• Sürümleme ve rehberler içeren portal: Docusaurus + OpenAPI eklentisi
• Elle yazılmış, editoryal kontrol edilen sayfalar: Slate
• Barındırılan bir projeden dışa aktarma: Apidog CLI

Daha geniş bir maliyetsiz araç görünümü için ücretsiz API dokümantasyon araçları derlemesine göz atabilirsiniz.

Özet

Açık kaynaklı bir API dokümantasyon CLI seçerken üç soruyu yanıtlayın:

1. Hangi lisansa ihtiyacınız var?
2. Markdown, HTML veya tam bir portal mı üretmelisiniz?
3. Dokümanlarınız statik bir spesifikasyondan mı, yoksa sürdürülen canlı bir projeden mi geliyor?

En küçük ihtiyacı karşılayan aracı seçin:

• Bir sayfa için Redocly CLI
• Markdown için Widdershins
• SDK'ların yanında dokümanlar için OpenAPI Generator veya Swagger Codegen
• Portal için Docusaurus
• Elle düzenlenen sayfalar için Slate

API'niz tek bir dosya yerine sürdürülen bir projede yaşıyorsa ve birden fazla aracı zincirlemek yerine doküman dışa aktarmayı tercih ediyorsanız, Apidog'u indirin ve bir projeye karşı apidog export komutunu deneyin. Bunu CI işinize ekleyerek API değiştiğinde dokümanları yeniden oluşturabilirsiniz; ancak Apidog'un açık kaynaklı bir ikili değil, freemium bir platform olduğunu dikkate alın.