DEV Community

Cover image for AI Ajanı Apidog CLI ile API Dokümantasyonunu Nasıl Oluşturur
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

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

API dokümantasyonu önemlidir; ancak yeni uç noktalar yayınlandığında referansların geride kalması, başlangıç kılavuzlarının eski kimlik doğrulama akışlarını anlatması sık görülen bir sorundur. Bu iş gerçek, tekrarlayıcı ve kolayca ertelenebilir.

Apidog'u bugün deneyin

Bu kombinasyon, yani önemli ama tekrarlayıcı ve ertelenebilir işler, bir yapay zeka aracısı için uygundur. Aracınız terminal komutları çalıştırabiliyorsa doğal dildeki isteğinizden uç noktalar oluşturabilir, bunların çevresindeki Markdown kılavuzlarını yazabilir ve dokümantasyon sitesini yayınlayabilir. Apidog CLI, her dokümantasyon işlemini betiklenebilir bir komuta dönüştürür ve komut sonuçlarını yapılandırılmış JSON olarak döndürür.

Neden GUI veya MCP sunucusu yerine CLI?

Bir aracının API dokümanlarınıza erişmesi için üç temel yaklaşım vardır. Her biri farklı bir problem çözer.

Yaklaşım Yön Kim yönlendirir? İncelenebilir fark var mı?
GUI Tarayıcıda insan düzenlemeleri Tıklayan kişi Hayır
MCP sunucusu Şartnameyi okur → kod yazar Editördeki aracı Kod deposunda, dokümanlarda değil
CLI Dokümanları doğrudan yazar Terminaldeki aracı Evet, her komut kaydedilir

Bir MCP sunucusu, aracının API tanımınızı okuması ve buna göre istemci kodu üretmesi için idealdir. Örneğin Cursor'ın MCP ile doküman akışı bu kullanım şekline uygundur.

Bu yazıdaki hedef farklıdır: aracının dokümantasyonu üretmesi. Yani:

  • Uç noktaları oluşturması
  • Veri şemalarını tanımlaması
  • Markdown kılavuzları yazması
  • Dokümantasyon sitesini yayınlaması

CLI bu senaryoda üç nedenle öne çıkar:

  1. Deterministiktir: Aynı komut, aynı girdilerle aynı sonucu üretir.
  2. Betiklenebilirdir: Akışı CI işlerinize veya ajan görev döngünüze ekleyebilirsiniz.
  3. Yönlendirme sağlar: JSON sonuçlarındaki agentHints.nextSteps alanı, aracının sıradaki komutu tahmin etmek yerine CLI önerisini izlemesini sağlar.

Aracının ortamını hazırlayın

Önce CLI'ı yükleyin ve kimlik doğrulaması yapın:

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

Kurulum kılavuzu Node sürümleri ve PATH yapılandırmasını; kimlik doğrulama kılavuzu ise token ve CI sırlarını kapsar.

Apidog CLI kurulumu

Token'ı Apidog uygulamasında kullanıcı avatarı → Hesap Ayarları → API Erişim Jetonu yolundan alın. Girişten sonra token yerel olarak saklanır; bu nedenle her komutta tekrar iletmeniz gerekmez.

API erişim token ayarları

Yazma işlemlerinde proje kimliği gerekir. Bu kimliği Proje Ayarları → Temel Ayarlar altında bulabilir veya terminalden listeleyebilirsiniz:

apidog project list
Enter fullscreen mode Exit fullscreen mode

Claude Code, Cursor, Codex veya kabuk komutu çalıştırabilen başka bir kodlama aracısı kullanabilirsiniz. CLI, komutu hangi aracının çağırdığını değil, komutun ve yükün geçerli olup olmadığını önemser.

CLI ajan iş akışı

Apidog CLI kullanımı

Aracı için zorunlu yazma döngüsü

Kaynak oluşturan dokümantasyon komutları JSON dosyaları alır. Aracınız JSON yükünü bellekten veya tahmin ederek oluşturmamalıdır. Uydurulmuş alan adları, başarısız komutların başlıca nedenidir.

Her yazma işleminde şu dört adımı uygulayın:

# 1. Komutun beklediği yük şemasını alın
apidog cli-schema get doc-create

# 2. Şemaya uygun JSON dosyasını oluşturun

# 3. Yazmadan önce yerelde doğrulayın
apidog cli-schema validate doc-create --file ./doc.json

# 4. Yalnızca doğrulama başarılıysa kaynağı oluşturun
apidog doc create --project <projectId> --file ./doc.json
Enter fullscreen mode Exit fullscreen mode

Bu kuralları sistem isteminize, CLAUDE.md dosyanıza veya .cursorrules dosyanıza ekleyin:

Apidog CLI kuralları:
- JSON yükünü asla tahmin ederek yazma. Önce `apidog cli-schema get <command>` çalıştır ve yükü bu şemadan üret.
- Her create veya update işleminden önce `apidog cli-schema validate <command> --file <file>` çalıştır.
- Tüm yazma komutlarında `--project <projectId>` parametresini kullan.
- Sonraki komutu seçmeden önce her JSON yanıtındaki `agentHints.nextSteps` alanını oku.
- Bir yazma işlemi izinler nedeniyle engellenirse dur ve kullanıcıdan onay iste; alternatif yol deneme.
Enter fullscreen mode Exit fullscreen mode

Bu döngü, “model alan adı uydurdu” hatasını yerel doğrulama aşamasında yakalar.

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

Apidog API referansını projedeki uç noktalardan ve veri şemalarından üretir. Bu nedenle önce yeniden kullanılabilir veri modellerini, ardından bunları kullanan uç noktaları oluşturun.

Örnek istek:

“Bir sipariş kimliği ve miktar alanı alan POST /refunds uç noktasını ekleyin. Başarı ve doğrulama hatası yanıtlarını belgeleyin.”

İlk olarak veri şemasını oluşturun. Şemayı almadan önce CLI'ın gereksinimlerini kontrol edin:

apidog cli-schema get schema-create
Enter fullscreen mode Exit fullscreen mode

Ardından refund-schema.json dosyasını oluşturun:

{
  "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" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Şimdi uç noktayı oluşturun. endpoint-create şeması, method ve path alanlarını gerektirir. Yeni oluşturduğunuz veri modelini #/definitions/{schemaId} biçimindeki $ref ile kullanabilirsiniz.

refunds-endpoint.json:

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

Doğrulayıp oluşturun:

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

/refunds referansı artık ekip tarafından düzenlenen aynı tanımdan oluşturulur. Ayrı bir “doküman dışa aktarma” adımı gerekmez: uç nokta oluşturulduğunda proje içinde canlıdır.

Adım 2: Referansın yanında kılavuzlar da oluşturun

API referansı tek başına yeterli değildir. Geliştiricilerin ayrıca aşağıdaki gibi içeriklere ihtiyacı vardır:

  • Başlangıç kılavuzu
  • Kimlik doğrulama açıklaması
  • İdempotentlik notları
  • Geçiş rehberi
  • Hata çözümleme adımları

Apidog'da bu içerikler, proje doküman ağacındaki Markdown belgeleri olarak tutulur ve doc komut grubuyla yönetilir.

doc-create şeması en az name alanını gerektirir. Markdown içeriği content alanında tutulur. folderId: 0, belgeyi kök klasöre yerleştirir.

Örnek quickstart.json:

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

Belge ağacını kontrol edin, JSON'ı doğrulayın ve belgeyi oluşturun:

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

Böylece aracınıza şunu söyleyebilirsiniz:

“Yeni geliştiriciyi API anahtarından ilk iadeye götüren bir hızlı başlangıç kılavuzu yaz.”

Aracı Markdown taslağını üretir, şemaya uygun JSON'a yerleştirir, doğrular ve doküman ağacına ekler.

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

Referans ve kılavuzlar hazır olduğunda dokümantasyon sitesini terminalden yayınlayabilirsiniz. Burada üç komut grubunu ayırmak önemlidir:

  • doc: Projenin API ağacındaki Markdown belgesi
  • docs-site: Barındırılan, herkese açık dokümantasyon sitesi
  • shared-doc: Bir kişi veya ortakla paylaşmak için bağlantı; tam site değildir

Temel yayınlama akışı:

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

Kullanım seçimi basittir:

  • Herkese açık, yapılandırılmış bir dokümantasyon sitesi için docs-site
  • Bir ortağa veya müşteriye gönderilecek bağlantı için shared-doc
  • Proje içindeki Markdown sayfaları için doc

Bu işlem komut tabanlı olduğu için aracınız her doküman değişikliğinden sonra yayınlama adımını otomatik olarak çalıştırabilir.

Adım 4: Taşınabilir kopya dışa aktarın

Dokümanları başka bir yerde barındırmak veya başka araçlarda kullanmak istiyorsanız export komutunu kullanın.

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
Enter fullscreen mode Exit fullscreen mode

Bir projede birden fazla hizmet varsa yalnızca belirli kaynakları dışa aktarmak için yardım çıktısını inceleyin:

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Çıktıyı daraltmak için --scope, --api-ids ve --folder-ids bayraklarını kullanabilirsiniz.

Uçtan uca örnek

İstek:

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

Aracının çalıştıracağı komutlar:

# 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

# Uç noktaları oluşturun
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# İdempotentlik kılavuzunu oluşturun
apidog doc create --project $PID --file ./idempotency-guide.json

# Doküman sitesini yayınlayın
apidog docs-site create --project $PID --file ./docs-site.json
Enter fullscreen mode Exit fullscreen mode

Bu noktada yapmanız gereken iş, oluşan farkı incelemek ve sonucu onaylamaktır.

Akışı CI veya aracı görev döngüsüne ekleyin

Her adım bir CLI komutu olduğundan, dokümantasyon akışını CI sistemine ekleyebilirsiniz.

Her push işleminde Markdown API referansı dışa aktaran minimal GitHub Actions 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
Enter fullscreen mode Exit fullscreen mode

Daha kapsamlı aracı iş akışları 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.

Temel desen aynıdır:

  1. Niyeti doğal dilde açıklayın.
  2. Aracının bunu doğrulanmış CLI komutlarına dönüştürmesini sağlayın.
  3. Oluşan sonucu inceleyin.

İzinler hakkında not

Bir aracıyla proje üzerinde yazma işlemi engellenebilir. Bir create komutu engellenmiş olarak dönerse, ilgili dal için Harici Yapay Zeka Düzenleme İzinleri kapalı olabilir.

İki seçeneğiniz vardır:

  1. Apidog istemcisinde Proje Ayarları → Özellik Ayarları → Yapay Zeka Özellik Ayarları bölümünden doğrudan düzenleme iznini etkinleştirmek. Bu ayar Apidog istemcisi 2.8.32+ sürümünde kullanılabilir.
  2. Aracının izole bir Yapay Zeka dalında çalışmasını ve ardından bir birleştirme isteği açmasını sağlamak.

API belirtimini yapay zeka aracısıyla güncelleme kılavuzu, Yapay Zeka dalı akışını ayrıntılı olarak açıklar.

Yaygın sorunlar

  • Aracı JSON'ı elle oluşturdu: En yaygın hatadır. cli-schema get → cli-schema validate → create sırasını zorunlu tutun.
  • Proje kimliği eksik: Her doc, docs-site ve export çağrısında okunabilir proje adı yerine --project <projectId> kullanın.
  • doc, docs-site ve shared-doc karıştırıldı: Bunlar sırasıyla Markdown sayfası, barındırılan site ve paylaşım bağlantısıdır.
  • CI ortamında token yok: apidog login token'ı yalnızca çalışan makinede saklar. Her yeni CI çalıştırıcısında işin başında login --with-token çalıştırın.
  • Geçersiz $ref: Bir uç nokta #/definitions/{schemaId} ile şemaya referans veriyorsa şema önce oluşturulmuş olmalıdır.

Sıkça Sorulan Sorular

Hangi yapay zeka aracıları Apidog CLI kullanabilir?

Kabuk komutları çalıştırabilen tüm aracı türleri kullanılabilir: Claude Code, Cursor, Codex ve benzeri kodlama aracıları. CLI aracıdan bağımsızdır; geçerli komutlara ve yüklere ihtiyaç duyar.

Ücretli plan gerekli mi?

Hayır. Apidog açık kaynak değildir; ancak ücretsiz katman ve apidog-cli, bu yazıda açıklanan oluşturma ve yayınlama akışını kapsar.

Aracı mevcut dokümanların üzerine yanlışlıkla yazabilir mi?

create komutu yeni kaynak ekler. Var olan kaynakları değiştirmek için update kullanılır. Güncelleme akışı farklı koruyucu önlemler gerektirir ve API belirtimini güncelleme kılavuzunda ele alınır.

Bu yaklaşım yapay zeka doküman oluşturucularından nasıl farklıdır?

Genel yapay zeka doküman araçları koddan metin üretir. Bu akış ise API platformunuzdaki canlı kaynaktan yapılandırılmış dokümantasyon üretir: uç noktalar, şemalar, kılavuzlar ve yayınlanmış dokümantasyon sitesi aynı kaynağa dayanır.

Özet

Apidog CLI çalıştırabilen bir aracı, genellikle ertelenen dokümantasyon işlerini üstlenebilir: uç noktaları oluşturur, kılavuzları yazar ve dokümantasyon sitesini yayınlar. Siz dokümanları sıfırdan yazmak yerine oluşan farkı incelemeye odaklanırsınız.

Güvenilir sonuç için temel kural şudur:

Şemayı al → yükü oluştur → doğrula → yaz
Enter fullscreen mode Exit fullscreen mode

Aracınıza bu döngüyü, kurallar bloğunu ve proje kimliğini verdiğinizde dokümantasyon kodun gerisinde kalan bir iş olmaktan çıkar.

Apidog'u indirin veya tam komut referansı için Apidog CLI tam kılavuzunu okuyun.

Top comments (0)