Redocly'den Apidog'a Docs-as-Code İş Akışınızı Kaybetmeden Nasıl Geçilir?

Geliştirici portalınızı Redocly üzerinde çalıştırıyorsanız, çoğu API ekibinin istediği şekilde çalışıyorsunuz demektir: openapi.yaml Git'te yaşar, kılavuzlar Markdown'dır ve bir push belgeleri günceller. Araç değiştirirken korkulan şey bu döngüyü kaybetmek ve belgeleri bir web arayüzünde elle düzenlemeye başlamaktır.

Buna mecbur değilsiniz. Apidog Spec-first Mode, spec'inizi ve Markdown'ınızı aynı depoda tutar, her push'ta bir webhook aracılığıyla senkronize eder ve tek bir kenar çubuğunda kılavuzlar ile bir API referansı içeren bir portal yayımlar. Bu kılavuz, geçiş sürecini adım adım anlatıyor; otomatik olarak taşınmayan tek kısım da dahil: birçok Redocly kullanıcısının info.description ve tags[].description içinde tuttuğu uzun içerik.

Hâlâ araçları karşılaştırıyorsanız, Apidog vs. Redocly veya daha geniş Redocly alternatifleri listesiyle başlayın. Bu yazı, Apidog'u seçtiğinizi ve iş akışınızı bozmadan geçmek istediğinizi varsayıyor.

Neler taşınır, neler taşınmaz

Bu geçişi gerçek bir üretim spec'i ile test ettik: OpenAPI 3.0.3, 13 tag genelinde 62 operasyon, spec'in description alanlarına yazılmış başlangıç, kimlik doğrulama ve entegrasyon içeriğiyle. İçe aktarma sırasında olanlar şöyle.

API referansı hiçbir düzenleme olmadan taşınıyor. Eksik kalan kısım anlatı içeriği.

Description alanlarınız neden aynı şekilde render edilmiyor

Redocly'nin referans dokümanlarının arkasındaki render edici olan Redoc, info.description'ı mini bir doküman olarak ele alır. İçindeki her Markdown başlığı bir kenar çubuğu girdisi haline gelir, bu yüzden ekipler genellikle tüm "Başlangıç" ve "Kimlik Doğrulama" kılavuzlarını oraya yazar. Tag açıklamaları her tag grubunun üstünde tanıtım metni olarak render edilir.

Bu bir Redoc geleneğidir, OpenAPI Specification'ın bir parçası değildir. Spec, description'ı yalnızca bir CommonMark string'i olarak tanımlar. Apidog, çoğu portal gibi, kılavuzları bağımsız Markdown dokümanları olarak tutar ve spec'i referans için saklar. İçe aktarma sonrası yapılan varsayılan bir yayım yalnızca API referansını gösterir; description alanlarına yazdığınız kılavuzlar olmadan.

Çözüm tek seferlik bir taşıma işlemidir: bu içeriği YAML'den çıkarıp yanındaki Markdown dosyalarına taşımak. Sonrasında her şey Git tabanlı kalır.

Hedef depo düzeni

Doğruladığımız yapı şu:

your-repo/
├── openapi.yaml              # source of truth for the API reference
└── docs/
    ├── getting-started.md
    ├── authentication.md
    └── embed-integration-guide.md

openapi.yaml API referansını yönetir. docs/ içindeki her dosya portal kenar çubuğunda bir sayfa olur. Bu Markdown dosyalarının referans verdiği görseller aynı depoda bulunabilir ve onlarla birlikte senkronize edilebilir.

Navigasyonunuzu sıralamak için Redocly'nin sidebars.yaml dosyasını kullandıysanız, referans olarak saklayın. Aynı sıralamayı Apidog'un docs site ayarlarında bir kez ayarlayacaksınız.

Adım adım geçiş

1. Description alanlarınızın içinde ne olduğunu denetleyin

Herhangi bir şeyi taşımadan önce, spec'te ne kadar içerik olduğuna bakın. yq ile:

# How long is the top-level description?
yq '.info.description' openapi.yaml | wc -w

# Which headings does it contain? Each one is a Redoc sidebar entry today.
yq '.info.description' openapi.yaml | grep -E '^#{1,3} '

# Which tags carry a description?
yq '.tags[] | select(.description != null) | .name' openapi.yaml

Başlık listesi gelecekteki docs/ dosya listenizdir. Testimizde info.description iki Markdown dosyasına bölündü ve tag açıklamaları klasör başına tanıtım sayfaları ile bir ek Markdown dosyası haline geldi.

2. info.description'ı Markdown dosyalarına bölün

Her üst düzey bölümü docs/ altında kendi dosyasına kopyalayın. Başlıkları, kod örneklerini ve bağlantıları koruyun. Ardından spec'teki info.description'ı tek paragraflık bir özete indirin, böylece içerik yalnızca tek bir yerde yaşasın.

Kopyalarken Redoc'a özgü iki özelliğe dikkat edin:

• <SecurityDefinitions /> ve benzer Redoc etiketleri Redoc dışında render edilmez. Bunları, referanstaki güvenlik şemalarına bağlantı veren kısa bir yazılı bölümle değiştirin.
• #tag/Payments gibi bağlantılar Redoc anchor'larına işaret eder. İlk yayımdan sonra bunları eşleşen Apidog doküman veya klasör URL'leriyle güncelleyin.

3. Depoyu Spec-first Mode'da bağlayın

Spec-first Mode'da bir proje oluşturun, deponuzu bağlayın (GitHub, GitLab, Azure DevOps veya Bitbucket), openapi.yaml ve docs/ klasörüne işaret edin ve webhook'u kurun. O andan itibaren, izlenen dala yapılan bir push projeyi günceller.

İlk senkronizasyondan sonra, Specs çalışma alanı spec'inizi ve deponun geri kalanını gösterir. APIs sekmesi openapi.yaml'dan ayrıştırılan operasyonları listeler, Docs Markdown sayfalarınızı barındırır ve All files depoyu yansıtır.

Webhook, bunu bir docs-as-code iş akışı olarak tutan şeydir. O olmadan senkronizasyonları elle tetiklemeniz gerekirdi. Bunun neden önemli olduğuna dair bir hatırlatma için docs as code kılavuzumuza bakın.

4. Docs sitesini yayımlayın ve navigasyonu ayarlayın

Projeden bir docs sitesi yayımlayın ve kenar çubuğunu düzenleyin. Çoğu Redocly kullanıcısının istediği ve bizim de yeniden oluşturduğumuz sıralama şu:

1. Getting Started
2. Authentication
3. Integration guides
4. API Reference (tag'lerinizden gelen endpoint klasörleri)

Markdown sayfaları ve API klasörleri tek bir ağaçta serbestçe karışır, böylece mevcut Redocly kenar çubuğunuzu yakından eşleştirebilirsiniz.

5. Özel alan adınızı ekleyin

developers.example.com gibi bir CNAME'i docs sitesine yönlendirin. Özel alan adları Free planında kullanılabilir.

Kodlama ajanınızın tag açıklamalarını Apidog CLI ile taşımasına izin verin

Tag açıklamaları en sıkıcı kısımdır. On üç tag, on üç kopyala-yapıştır işi demektir ve geçiş sırasında bir tag açıklaması her değiştiğinde bunları yeniden yaparsınız. Bunu bunun yerine kodlama ajanınıza devredin.

Apidog CLI, Claude Code, Codex, Cursor veya herhangi bir terminal ajanına endpoint klasörleri dahil projenize yapılandırılmış JSON erişimi sağlar. Bir kez kurun:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_ACCESS_TOKEN>
npx -y skills add https://apidog.com

Son satır, ajanınızın komutları tahmin etmeden bilmesi için Apidog skill'ini kurar. Kurulum kılavuzu token'ları ve özel dağıtımları kapsar.

Ardından ajanınıza tek bir prompt verin:

openapi.yaml'ı oku. Açıklaması olan her tag için, Apidog projesi <PROJECT_ID> içinde eşleşen endpoint klasörünü bul ve o klasörün açıklamasını tag'in açıklamasına ayarla. Yazmadan önce her payload'ı apidog cli-schema validate folder-update ile doğrula. Değiştirdiğin klasörlerin listesini bana göster.

Ajanın çalıştırdıkları şöyle:

# Find the folder IDs that correspond to your tags
apidog folder list --project <PROJECT_ID> --type endpoint

# Check the payload shape instead of guessing it
apidog cli-schema get folder-update

# For each tag: write {"description": "..."} to a file, validate, then update
apidog cli-schema validate folder-update --file ./payments-folder.json
apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \
  --file ./payments-folder.json

folder-update şeması name, parentId ve description kabul eder ve description endpoint ile test senaryosu klasörlerinde desteklenir. Tek bir tag'e ait olmayan kılavuzlar için ajan, apidog cli-schema get doc-create'i okuduktan sonra aynı şekilde apidog doc list ve apidog doc create komutlarını kullanabilir.

Bir klasörün tanıtımını yayımlanmış sitede göstermek için, klasörün ayarlarında Documentation Settings after Publication altındaki Folder Contents Displaying Setting'i ayarlayın.

Dürüst bir uyarı: tag açıklamalarını kategori başına tanıtım sayfaları olarak göstermek işe yarar, ancak daha az belgelenmiş bir yola dayanır. Hepsine bağlı kalmadan önce kendi çalışma alanınızda iki veya üç klasörde test edin. Ajan odaklı daha fazla spec çalışması için Apidog CLI'yi Claude Code'da kullanma ve bir ajanın API spec'inizi güncellemesine izin verme yazılarımıza bakın.

Git dışında kalanlar

Bir Spec-first projesi API'nizi ve Markdown'ınızı Git'te tutar. Birkaç portal ayarı Apidog arayüzünde yaşar ve sürüm kontrolünde değildir:

Bunlar bir kez ayarlanan öğelerdir. Her içerik değişikliğinde değil, yeni bir üst düzey bölüm eklediğinizde bunlara dokunursunuz. Redocly bunların daha fazlasını redocly.yaml ve sidebars.yaml içinde tutar, dolayısıyla bugün navigasyon değişikliklerini pull request'lerde inceliyorsanız, bunun arayüze taşınacağını planlayın.

Plan ve fiyatlandırma

Burada açıklanan kurulum, özel alan adı dahil olmak üzere Free planına uyar. Free, 4 ekip üyesine kadar kapsar. Ücretli planlar, proje başına birden fazla dokümantasyon sitesi ve özel görünürlük kontrolleri gibi şeyler ekler. Güncel limitler için Apidog fiyatlandırmasına bakın.

Geçişten sonra Redocly vs. Apidog

Değişim basit. YAML ile tanımlanan navigasyonu kaybediyorsunuz. Dokümanlarınızın kaynaklandığı aynı spec üzerinde test, mocking ve ajan dostu bir CLI kazanıyorsunuz. CLI bazında bir karşılaştırma için Apidog CLI vs Redocly CLI yazısını okuyun.

SSS

Redocly üzerinde barındırılan URL'lerim çalışmaya devam edecek mi? Otomatik olarak değil. Sayfa yolları değişir. Eski portalınızda yüksek trafikli kılavuz URL'leri varsa, alan adını değiştirdikten sonra ana sayfalar için DNS veya proxy katmanınızda yönlendirmeler ekleyin.

OpenAPI spec'imi yeniden yazmak zorunda mıyım? Hayır. Spec olduğu gibi içe aktarılır. Yalnızca anlatı içeriğini info.description ve tags[].description'dan Markdown dosyalarına taşırsınız.

x-tagGroups'u koruyabilir miyim? Gruplama için bunun yerine klasörleri kullanın. Her tag bir klasör olur ve tag gruplarınızı yeniden oluşturmak için klasörleri iç içe yerleştirebilirsiniz.

Bu, Stoplight'tan geçişle nasıl karşılaştırılır? Şekil benzer: Git'te spec, yanında Markdown, webhook senkronizasyonu. Her iki aracı da kullanıyorsanız Stoplight'tan Apidog'a nasıl geçilir yazısına bakın.

Bir adım benim çalışma alanımda farklı davranırsa ne olur? Sonuçlarımız bir test ortamından geldi. Önce bir branch üzerinde içe aktarmayı yeniden çalıştırın ve DNS'i değiştirmeden önce yayımlanmış portalı mevcut olanla karşılaştırın.

Geçişi bir öğleden sonrada yapın

Redocly'den Apidog'a geçiş çoğunlukla bir içerik taşıma işlemidir. Spec'iniz olduğu gibi içe aktarılır. Kılavuzlarınız description alanlarından bir kez docs/ klasörüne taşınır. Bir webhook bundan sonra her şeyi senkronize tutar. Ajanınızın tekrarlayan tag açıklaması işini Apidog CLI ile halletmesine izin verin ve kendi zamanınızı yayımlanmış portalı sayfa sayfa kontrol etmeye harcayın.

Apidog'u indirin ve geçişe başlamak için deponuzu Spec-first Mode'a bağlayın.