AI Ajanı Apidog CLI ile API Dokümantasyonunu Nasıl Oluşturur

API dokümantasyonu, herkesin önemli olduğunu kabul ettiği ancak kimsenin sahiplenmek istemediği bir görevdir. Yeni bir uç nokta yayınlanır, referans bir hafta geride kalır ve başlangıç kılavuzu iki sprint önce değiştirdiğiniz bir kimlik doğrulama akışını açıklar. İş gerçek, ancak tekrarlayıcı ve ertelemeye elverişli.

Bu kombinasyon (önemli, tekrarlayıcı, ertelenebilir) tam da bir yapay zeka aracısının iyi olduğu bir alandır. Aracınız bir terminal komutunu çalıştırabiliyorsa, basit bir dil isteğiyle uç noktalar oluşturabilir, bunların etrafındaki metin kılavuzlarını yazabilir ve bir dokümantasyon sitesi yayınlayabilir. Apidog CLI bunu mümkün kılar: her dokümantasyon eylemi, bir aracının okuyup üzerinde işlem yapabileceği yapılandırılmış JSON çıktısı olan betiklenebilir bir komuttur.

Uygulamayı İndir

Neden CLI, GUI veya bir MCP sunucusu değil?

Bir aracının API dokümanlarınıza erişmesinin üç yolu vardır ve bunlar farklı sorunları çözer. Bu ayrımı doğru yapmak, araçlarınızla mücadele etmekle iş için tasarlanmış olanı kullanmak arasındaki farktır.

Yaklaşım	Yön	Kim yönlendirir	İncelenebilir fark var mı?
GUI	Bir tarayıcıda insan düzenlemeleri	Bir kişi, tıklayarak	Hayır
MCP sunucusu	Şartnamenizi okur → kod yazar	Editörünüzde bir aracı	Kod deponuzda, dokümanlarda değil
CLI	Dokümanları kendisi yazar	Bir terminalde bir aracı	Evet, her komut kaydedilir

Bir MCP sunucusu, bir aracının API tanımınızı okumasını ve buna karşı istemci kodu oluşturmasını istediğinizde mükemmeldir. Cursor'ın MCP aracılığıyla doküman akışı tipik bir örnektir. Ancak bu, burada istediğimizin tersidir. Aracının dokümantasyonu üretmesini istiyoruz: uç noktalar oluşturmak, Markdown kılavuzları yazmak ve bir site yayınlamak.

Bunun için CLI üç açıdan kazanır. Deterministiktir: aynı komut aynı sonucu üretir. Betiklenebilirdir: tüm akış CI'a entegre olur. Ve her çağrıda, aracıya bir sonraki ne yapabileceğini söyleyen bir agentHints.nextSteps alanı dahil olmak üzere JSON döndürür. Bu son nokta duyulduğundan daha önemlidir: bu, aracının ileriye doğru tahmin etmediği, CLI'ın kendi önerilerini takip ettiği anlamına gelir.

Aracının ortamını kurun

CLI'ı yükleyin ve bir kez kimlik doğrulaması yapın. Kurulum kılavuzumuz Node sürümlerini ve PATH'i kapsar; kimlik doğrulama kılavuzu ise jetonları ve CI sırlarını kapsar.

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

Jetonu Apidog uygulamasından kullanıcı avatarı → Hesap Ayarları → API Erişim Jetonu altından alın. Giriş yaptıktan sonra yerel olarak saklanır, bu nedenle aracı her çağrıda bunu iletmez.

Her yazma işlemi, Proje Ayarları → Temel Ayarlar altında bulacağınız veya şunu çalıştırarak elde edeceğiniz bir proje kimliğine karşı yapılır:

apidog project list

Kabuk komutlarını çalıştırabilen herhangi bir kodlama aracısı burada işe yarar: Claude Code, Cursor, Codex ve diğerleri. CLI, onu kimin çağırdığını önemsemez; yalnızca komutların ve yüklerin doğru olmasını önemser. Bu da bizi her şeyi güvenilir kılan tek kurala getirir.

Bir aracının uyması gereken yazma ritüeli

Kaynak oluşturan dokümantasyon komutları bir JSON dosyası alır. Aracınız bu JSON'ı asla elle bellekten oluşturmamalıdır. Model tarafından uydurulan alan adları, başarısız çalıştırmaların bir numaralı nedenidir. CLI, her yazma işlemi için tam şemayı gönderir ve doğru sıra her zaman aynı dört adımdan oluşur:

# 1. CLI'ya yükün nasıl göründüğünü sorun
apidog cli-schema get doc-create

# 2. O şemadan JSON dosyasını oluşturun

# 3. Yazmadan önce doğrulayın (yerel olarak eksik bir alanı yakalar)
apidog cli-schema validate doc-create --file ./doc.json

# 4. Ancak şimdi gerçek komutu çalıştırın
apidog doc create --project <projectId> --file ./doc.json

Bu döngüyü aracının talimatlarına ekleyin. Bu, "model bir alan uydurdu" ifadesini "doğrulayıcı bunu benim makinemde reddetti" ifadesine dönüştürür ki bu, temiz bir çalıştırma ile başarısız bir derleme arasındaki farktır. İşte bir aracının sistem istemine veya bir CLAUDE.md / .cursorrules dosyasına doğrudan yapıştırabileceğiniz bir kurallar bloğu:

Apidog CLI kuralları:
- Asla elle bir JSON yükü yazmayın. Önce `apidog cli-schema get ` komutunu çalıştırın ve o şemadan oluşturun.
- Herhangi bir oluşturma veya güncelleme öncesinde her dosyayı `apidog cli-schema validate  --file ` ile doğrulayın.
- Yazma komutlarında her zaman --project  parametresini geçirin.
- Bir sonraki komutu seçmek için her JSON yanıtındaki `agentHints.nextSteps` alanını okuyun.
- Bir yazma işlemi izinler tarafından engellenirse, durun ve insana sorun; bir çözüm yolu seçmeyin.

Bu beş satır, dokümanları güvenilir bir şekilde gönderen bir aracı ile yükleri rastgele tahmin edip duvara çarpan bir aracı arasındaki farkı yaratır.

Adım 1: Uç noktalardan ve şemalardan referans oluşturun

Apidog'da, API referansınız projedeki uç noktalardan ve veri şemalarından oluşturulur. Bu nedenle aracının ilk görevi bunları oluşturmaktır. Diyelim ki ona şunu söylediniz:

“Bir sipariş kimliği ve bir miktar alan POST /refunds uç noktasını ekleyin ve başarı ile doğrulama-hata yanıtlarını belgeleyin.”

Aracı önce yeniden kullanılabilir veri modelini oluşturur, sonra onu referans alan uç noktayı. apidog cli-schema get schema-create komutunu çalıştırmak, bir veri şemasının bir name ve standart bir jsonSchema nesnesi aldığını gösterir. Böylece aracı refund-schema.json gibi bir şey yazar:

{
  "name": "Refund",
  "description": "A refund issued against an order",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amount"],
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "reason": { "type": "string" }
    }
  }
}

Doğrulayın ve oluşturun:

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json

Şimdi uç nokta. `endpoint-create` şeması `method` ve `path` gerektirir ve az önce oluşturduğunuz veri modelini `#/definitions/{schemaId}` formatında bir `$ref` ile referanslamanıza olanak tanır. Aracı `refunds-endpoint.json` dosyasını yazar:

{
  "name": "Create refund",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": { "$ref": "#/definitions/<refundSchemaId>" }
  }
}

apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json

/refunds için referans dokümantasyonu artık ekibinizin düzenlediği aynı tanımdan oluşturulmuş olarak mevcuttur. Referans için ayrı bir "dokümanları dışa aktar" adımı yoktur; uç nokta yayınlandığı anda projede canlıdır. Bu, şema-öncelikli bir kaynağın getirisi budur: referans kayamaz, çünkü o şema *kendisi*dir.

Adım 2: Sadece referansı değil, kılavuzları da yazın

Şemalardan oluşturulan bir referans, iyi bir dokümantasyonun yalnızca yarısıdır. Diğer yarısı ise düzyazıdır: bir başlangıç sayfası, bir kimlik doğrulama kılavuzu, bir geçiş notu. Apidog'da bunlar, doc komut grubu tarafından yönetilen Markdown belgeleri olarak projenin doküman ağacında yaşar.

doc-create şeması yalnızca bir name gerektirir; content Markdown'ı tutar ve folderId onu ağaca yerleştirir (0 köktür). Böylece aracının taslağını oluşturduğu bir hızlı başlangıç quickstart.json olur:

{
  "name": "Quickstart: Your first refund",
  "content": "# Quickstart\n\nThis guide takes you from API key to your first refund in five minutes...",
  "folderId": 0
}

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json

Aracının değerini kazandığı yer burasıdır. Ona "yeni bir geliştiriciyi API anahtarından ilk iadeye kadar götüren bir hızlı başlangıç yaz" diye sorduğunuzda, Markdown'ı taslaklar, şemanın beklediği yüke sarar, doğrular ve belgeyi oluşturur. Tarayıcı yok, kopyala-yapıştır yok. İçerik yalnızca bir dize alanı olduğu için, aracı görevin gerektirdiği kadar uzun veya ayrıntılı bir kılavuz yazabilir.

Adım 3: Doküman sitesini yayınlayın

Referans ve kılavuzlar yerinde olduğunda, aracı terminalden de yayınlayabilir. Bunu iki komut grubu ele alır ve bir isimlendirme farkı insanları sürekli şaşırtır:

doc: projenin API ağacının *içindeki* bir Markdown belgesi (2. adımda oluşturduğunuz).
docs-site: barındırılan, herkese açık dokümantasyon sitesi.
shared-doc: bir ortağa vermek için paylaşılabilir bir bağlantı, tam bir site değil.

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json

Terminalden tanımlanmış herkese açık bir site istediğinizde docs-site'a, birine göndermek için sadece bir bağlantıya ihtiyacınız olduğunda ise shared-doc'a başvurun. Her ikisi de komut olduğu için, yayınlama işlemi aracının her doküman değişikliğinden sonra çalıştırdığı betiklenmiş bir adım haline gelir; barındırılan site, komut döndüğü anda güncellemeyi yansıtır.

Adım 4 (isteğe bağlı): Taşınabilir bir kopyayı dışa aktarın

Bazen dokümanları bir dosya olarak istersiniz: başka bir yerde barındırmak için bir HTML sayfası, statik site oluşturucu için Markdown veya aşağı akışa vermek için OpenAPI. export komutu her üçünü de üretir:

apidog export --project <projectId> --format html --output ./api-docs.html
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json

Projeniz birkaç hizmet içeriyorsa ve yalnızca bir kısmını belgelemek istiyorsanız, apidog export --help çıktıyı daraltmak için `--scope`, `--api-ids` ve `--folder-ids` bayraklarını gösterir. Bu şekilde tek bir proje, hizmet başına bir doküman dosyası gönderebilir.

Uçtan uca tam bir örnek

İşte tüm döngü, tek bir basit dildeki istek ve bir aracının bunu yerine getirmek için çalıştırdığı komutlar.

Siz: “POST /refunds ve GET /refunds/{id} ile bir ödeme hizmeti ekledik. Her ikisini de belgeleyin, idempotentlik anahtarlarını açıklayan kısa bir kılavuz yazın ve bunu doküman sitemize yayınlayın.”

Aracı, kurallarını takip ederek şunları çalıştırır:

# Paylaşılan veri modelini oluşturun
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# Her iki uç noktayı da oluşturun
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# İdempotentlik kılavuzunu bir Markdown belgesi olarak yazın
apidog doc create --project $PID --file ./idempotency-guide.json

# Yayınla
apidog docs-site create --project $PID --file ./docs-site.json

Ortaya çıkan farkı incelersiniz ve ödeme hizmeti belgelenmiş ve canlıdır. Eskiden bir öğleden sonra süren bağlam değiştirme, artık bir istek ve bir incelemeden ibaret.

Bir aracı döngüsüne veya CI'ya bağlayın

Her adım bir komut olduğundan, tüm akış CI'ya veya bir aracının görev döngüsüne entegre olur. Her push işleminde Markdown referansınızı yeniden oluşturan ve commit eden minimal bir adım:

- name: API dokümanlarını yeniden oluştur
  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

CLI'a karşı uçtan uca bir aracı çalıştırmanın daha eksiksiz bir resmi için PRD'den Test Döngüsüne ve Eksiksiz Bir API Oluşturmak İçin 5 Yapay Zeka Aracısı Nasıl Kurulur yazılarına bakın. Her ikisindeki desen buradakiyle aynıdır: niyeti açıklayın, aracının bunu doğrulanmış CLI çağrılarına dönüştürmesine izin verin, sonucu gözden geçirin.

Bir izin notu

Bir aracı aracılığıyla bir projeye yazma işlemi engellenebilir. Bir create komutu engellenmiş olarak geri dönerse, projenin ilgili dalı için Harici Yapay Zeka Düzenleme İzinleri kapalıdır. İki dürüst seçeneğiniz var: Proje Ayarları → Özellik Ayarları → Yapay Zeka Özellik Ayarları (Apidog istemcisi 2.8.32+) içinde doğrudan düzenleme iznini etkinleştirin veya aracının izole bir Yapay Zeka dalında çalışmasını sağlayıp bir birleştirme isteği açın. API belirtiminizi güncelleme hakkında tamamlayıcı kılavuz, Yapay Zeka dalı akışını tüm ayrıntılarıyla anlatır ve aracı korumalı bir dalda dokümantasyon *oluştururken* de eşit şekilde geçerlidir.

Yaygın sorunlar

Aracı JSON'ı elle oluşturdu. Bu bir numaralı hatadır. Aracının talimatlarında cli-schema get → cli-schema validate → create zorunluluğunu uygulayın, böylece gerçek şemadan çalışır, tahmin edilen bir şemadan değil.
Eksik proje Kimliği. Her doc, docs-site ve export çağrısı, ayarlar kısmındaki Kimliği olan --project <projectId> gerektirir, okunabilir proje adını değil. Çoğu "hata verdi" raporu bu yüzdendir.
doc, docs-site ve shared-doc arasındaki karışıklık. Bunlar üç farklı şeydir: ağaçta bir Markdown sayfası, barındırılan bir site ve bir paylaşım bağlantısı. Aracının yazmadan önce görevin hangisini kastettiğini onaylamasını sağlayın.
CI'da jeton ayarlanmadı. apidog login jetonu çalıştıran makinede saklar. Yeni bir CI çalıştırıcısında hiçbiri yoktur, bu yüzden herhangi bir komuttan önce aynı işte login --with-token komutunu çalıştırın ve jetonu bir sırda saklayın.
Hiçbir yere işaret etmeyen bir $ref. Bir uç nokta, #/definitions/{schemaId} ile bir veri modeline referans verdiğinde, o şemanın önce var olması gerekir. Şemaları, onları kullanan uç noktalardan önce oluşturun.

Sıkça Sorulan Sorular

Hangi yapay zeka aracıları Apidog CLI'yı kullanabilir? Kabuk komutlarını çalıştırabilen herhangi bir aracı: Claude Code, Cursor, Codex ve benzeri kodlama aracıları. CLI, aracıdan bağımsızdır; yalnızca doğru komutlara ve geçerli yüklere ihtiyaç duyar.
Ücretli bir plana ihtiyacım var mı? Hayır. Apidog açık kaynak değildir, ancak ücretsiz katman ve apidog-cli burada açıklanan oluşturma ve yayınlama akışını kapsar.
Aracı mevcut dokümanları yanlışlıkla üzerine yazabilir mi? create yeni kaynaklar ekler. Mevcut olanları değiştirmek için update kullanılır, bu farklı davranır ve kendi koruyucu önlemlerine ihtiyaç duyar; bu, API belirtiminizi güncelleme hakkında tamamlayıcı kılavuzda ele alınmıştır.
Bu, bir yapay zeka doküman oluşturucudan nasıl farklıdır? Genel yapay zeka doküman araçları kodunuzdan metin üretir. Bu ise, ekibinizin düzenlediği şeyden sapmayacak tek bir canlı kaynaktan API platformunuz içinde *yapılandırılmış* dokümantasyon (uç noktalar, şemalar, kılavuzlar ve yayınlanmış bir site) üretir.

Özet

Apidog CLI'yı çalıştırabilen bir aracı, insanların her zaman ertelediği dokümantasyon kısmını sahiplenebilir: uç noktaları oluşturur, bunların etrafındaki kılavuzları yazar ve siteyi yayınlar. Tüm bunlar, her yazma işlemini koruyan şema doğrulamasıyla, basit bir dil isteğinden yapılır. Rolünüz doküman yazmaktan bir farkı incelemeye kayar.

Onu güvenilir kılan tek kural, yazma ritüelidir: şemayı alın, doğrulayın, sonra oluşturun. Aracınıza bu döngüyü, yukarıdaki beş satırlık kurallar bloğunu ve bir proje Kimliği verin, dokümantasyon kodun arkasında kalan bir angarya olmaktan çıkar. CLI'ı edinmek için Apidog'u indirin veya tam komut referansı için Apidog CLI tam kılavuzunu okuyun.

Uygulamayı İndir