Yapay Zeka Aracınızın Apidog CLI ile API Spesifikasyonunuzu Güncellemesini Nasıl Sağlarsınız

Bir API spesifikasyonunu elle düzenlemek zahmetlidir. Bir alanı yeniden adlandırmak, enum değeri eklemek veya gerekli bir alanı sıkılaştırmak gibi küçük değişikliklerin bile, referans veren uç noktaları bozmadan doğru uygulanması gerekir. Bu hassas ve mekanik iş akışı, doğru koruyucu önlemlerle bir yapay zeka aracısına devredilebilir.

Apidog'u bugün deneyin

Apidog CLI, bir aracının spesifikasyonu sorumlu biçimde değiştirmesi için gereken araçları sağlar:

• Her yazmadan önce şema doğrulama
• İzole bir Yapay Zeka dalında çalışma
• İncelemeniz için birleştirme isteği oluşturma

Bu yaklaşım, bir aracının API dokümantasyonu oluşturmasına izin vermenin mutasyon tarafıdır. Doküman oluşturma ekleyici ve düşük risklidir; mevcut bir API sözleşmesini değiştirmek ise güvenlik kontrolleri gerektirir.

CLI'da “spesifikasyonu güncellemek” ne anlama gelir?

Apidog'daki spesifikasyon; projedeki uç noktalar, veri şemaları ve bunların ilişkileridir. Güncelleme için üç temel komut vardır:

• endpoint update: Yol, parametre veya yanıt değiştirir.
• schema update: Uç noktaların kullandığı veri modelini değiştirir.
• import: Yeni bir OpenAPI dosyasını projeyle uzlaştırır.

Bir aracıya bu komutları kullandırmadan önce iki kritik davranışı anlamalısınız:

1. Yazma izinleri
2. Verileri sessizce silebilen tam değiştirme davranışı

Kritik tuzak: update tam değiştirme yapar

Aracınıza öğretmeniz gereken en önemli kural şudur: CLI'daki update komutları JSON Patch değildir.

Gönderdiğiniz alanlar doğrudan yazılır; diziler kimliğe göre birleştirilmez. Örneğin yalnızca bir parametreyi değiştirmek için kısmi bir parameters dizisi gönderirseniz, tek parametreyi düzenlemiş olmazsınız. Tüm diziyi yalnızca gönderdiğiniz içerikle değiştirirsiniz.

Doğru iş akışı her zaman oku → değiştir → doğrula → yaz olmalıdır:

# 1. Mevcut kaynağın TAMAMINI alın
apidog endpoint get <endpointId> --project <projectId>

# 2. Tam yapıyı yerelde düzenleyin.
# Değiştirmediğiniz alanları koruyun.

# 3. Tam nesneyi CLI şemasına göre doğrulayın
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. Tam nesneyi geri yazın
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json

Aracınızın talimatlarına şu kuralı açıkça ekleyin:

update komutuna asla kısmi nesne gönderme. Her zaman kaynağın tamamını getir, değiştir ve tam nesneyi geri yaz.

get adımını atlayan bir aracı alanları sessizce düşürebilir. cli-schema validate çalıştırmak ise hatalı yükleri projeye ulaşmadan yakalar.

Güvenli yol: Yapay Zeka dalında çalışın

Aracıya ana dalda doğrudan düzenleme izni verebilirsiniz; ancak başlangıçta bunu yapmayın.

Apidog'un Yapay Zeka dalı, aracının kaynak dalı değiştirmeden düzenleme yapmasını sağlayan bir izolasyon mekanizmasıdır. Siz onaylamadan hiçbir değişiklik ana dala birleşmez. Bunu API spesifikasyonunuz için bir çekme isteği gibi düşünebilirsiniz.

Adım 1: Yapay Zeka dalını oluşturun

apidog branch create --project <projectId> --type ai \
  --from main --name "ai/20260713-from-main-refund-fields"

Dal adı için şu biçimi kullanın:

ai/YYYYAAgg-kaynak-özellik

Bu sayede dalın kaynağı ve amacı ilk bakışta anlaşılır.

--from değeri ana dalınız veya normal bir sprint dalı olmalıdır; genel bir dal olmamalıdır. Kaynağından farkı olmayan bir Yapay Zeka dalı 24 saat sonra otomatik olarak arşivlenir.

Adım 2: Düzenlenecek mevcut kaynakları dala alın

Bir Yapay Zeka dalı boş başlar; kaynak dalı otomatik olarak klonlanmaz.

Aracının mevcut bir uç noktayı veya şemayı değiştirebilmesi için önce kaynağı pick-to ile dala alması gerekir:

apidog branch pick-to --project <projectId> --type ai \
  --from main --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>

Bu işlem yalnızca mevcut kaynakları değiştirmek veya silmek için gereklidir. Aracının dal üzerinde oluşturduğu yeni kaynaklar için pick-to gerekmez.

Bu adımı atlarsanız, aracının düzenleyeceği kaynak bulunmaz.

Adım 3: Değişikliği Yapay Zeka dalında yapın

Aracı artık aynı oku-değiştir-yaz döngüsünü çalıştırabilir. Ancak tüm komutlarda --branch ile Yapay Zeka dalını hedeflemelidir:

apidog endpoint get <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

apidog endpoint update <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json

Bu süreçte ana dalınıza hiçbir yazma işlemi yapılmaz. Bir hata oluşursa, etki alanı yalnızca geçici Yapay Zeka dalıdır.

Adım 4: İnceleyin, ardından birleştirin

Yapay Zeka dalındaki değişiklikler otomatik olarak ana dala yazılmaz. Aracı işlemi tamamladığında, sonucu siz incelersiniz.

Hedef dal korunuyorsa doğrudan birleştirmek yerine birleştirme isteği açın:

apidog merge-request --help

apidog branch merge --project <projectId> --type ai \
  --from "ai/20260713-from-main-refund-fields" \
  --to main \
  --endpoint-ids <ids>

Farkı inceleyin, onaylayın ve değişikliği ana dala alın.

CLI üzerinden doğrudan birleştirme, hem kaynak hem hedef dalda doğrudan düzenleme izni gerektirir. Ana dal korumalıysa merge-request kullanın ve isteği Apidog istemcisinden onaylayın.

Uygulamalı örnek: Bir alanı güvenli biçimde yeniden adlandırmak

Refund veri modelindeki amount alanını, tam sayı kuruş değerlerine geçmek için amountCents olarak yeniden adlandırmak istediğinizi varsayalım.

Aracıya şu görevi verin:

Refund şemasındaki amount alanını amountCents olarak yeniden adlandır ve türünü tam sayı yap.

İlk olarak Yapay Zeka dalındaki tam şemayı alın:

apidog schema get <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields"

Aracı, dokunmadığı alanları koruyarak tam jsonSchema nesnesini düzenlemelidir:

{
  "name": "Refund",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amountCents"],
    "properties": {
      "orderId": { "type": "string" },
      "amountCents": { "type": "integer" },
      "reason": { "type": "string" }
    }
  }
}

Buradaki önemli nokta: Aracı yalnızca değişen alanı göndermemelidir. orderId ve reason dahil tüm şema korunmalıdır, çünkü update birleştirme değil değiştirme yapar.

Ardından doğrulama ve yazma adımlarını çalıştırın:

# 1. Tam nesneyi doğrulayın
apidog cli-schema validate schema-create --file ./refund-full.json

# 2. Yapay Zeka dalına yazın
apidog schema update <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json

Son olarak dal farkını inceleyin. Beklenen fark yalnızca alan adının ve türünün değişmesidir. Onaydan sonra değişikliği birleştirin.

Birleştirmeden önce bozucu değişiklikleri işaretleyin

Gerekli bir alanı yeniden adlandırmak bozucu değişikliktir. Örneğin amount gönderen istemciler artık doğrulamayı geçemez.

Aracının bu tür değişiklikleri sessizce birleştirmemesi için kurallarına aşağıdaki kontrol noktasını ekleyin:

Herhangi bir spesifikasyon değişikliğini birleştirmeden önce sınıflandır:

- Bozucu olmayan:
  Yeni isteğe bağlı alan, yeni uç nokta veya gevşetilmiş kısıtlama.
  → Özeti oluştur ve birleştirme isteğine devam et.

- Bozucu:
  Yeniden adlandırılmış veya kaldırılmış alan, yeni gerekli alan,
  sıkılaştırılmış tür veya kısıtlama.
  → DUR.
  Bozucu değişikliği ve etkilenen uç noktaları bildir.
  Açık insan onayı olmadan birleştirme yapma.

Yapay Zeka dalı bu kontrolü güvenli hâle getirir: hiçbir şey otomatik birleşmediği için “dur ve bildir” gerçek bir onay kapısıdır.

OpenAPI dosyasından güncelleme

Bazen değişiklikler zaten koddan üretilmiş, başka bir ekip tarafından hazırlanmış veya harici olarak düzenlenmiş bir OpenAPI dosyasında bulunur.

Bu durumda alanları tek tek değiştirmek yerine dosyayı projeyle uzlaştırabilirsiniz:

apidog import --project <projectId> --format openapi --file ./openapi.json \
  --branch "ai/20260713-from-main-refund-fields"

import, OpenAPI 3.x, Swagger 2.0, Postman ve diğer formatları kabul eder.

Gelen değişiklikleri ana dala ulaşmadan incelemek için içe aktarmayı önce Yapay Zeka dalında çalıştırın. Birleştirmeden sonra sonucu doğrulamak amacıyla uzlaştırılmış spesifikasyonu dışa aktarın:

apidog export --project <projectId> --format openapi \
  --oas-version 3.1 --output ./openapi.json

Bu yöntem, doğruluk kaynağının Apidog dışında olduğu senaryolar için uygundur. Alan bazlı update yöntemi ise Apidog'un doğruluk kaynağı olduğu ve cerrahi değişiklikler yaptığınız durumlarda daha uygundur.

Aracı hata yaptığında geri alma

Yapay Zeka dalında çalışmanın en önemli avantajı, hatalı değişiklikleri geri almanın ucuz olmasıdır.

Aracı istemediğiniz bir sonuç üretirse, değişikliği ana dalla birleştirmeyin. Dalı arşivleyin:

apidog branch archive "ai/20260713-from-main-refund-fields" \
  --project <projectId> --type ai

Ana dal zaten doğru durumda kalır.

Kabul edilmiş farkı olmayan Yapay Zeka dalları 24 saat sonra otomatik olarak arşivlendiği için unutulmuş denemeler de temizlenir. Dal kullanmak bürokrasi değil, API spesifikasyonunuz için bir geri alma düğmesidir.

İzinler hakkında not

Bir update veya import işlemi engellenirse projenin Harici Yapay Zeka Düzenleme İzinleri kapalı olabilir.

Bu, bilinçli bir güvenlik engelidir. Çözüm, yukarıdaki Yapay Zeka dalı akışıdır:

1. Aracı izole dalı düzenler.
2. Siz değişikliği incelersiniz.
3. Birleştirmeyi onaylarsınız.

Doğrudan düzenlemelere izin vermek isterseniz ayar şu konumdadır:

Proje Ayarları → Özellik Ayarları → Yapay Zeka Özellik Ayarları

Bu ayar Apidog istemcisi 2.8.32+ sürümünde bulunur.

Aracı bir izin engeliyle karşılaştığında sessizce geçici çözüm üretmesine izin vermeyin. Kararı bir insana bildirmelidir.

Yaygın aksaklıklar

Kısmi güncelleme alanları sildi

En yaygın ve en zararlı hatadır. update birleştirmez, değiştirir.

Çözüm: Tam nesneyi alın, tamamını düzenleyin, doğrulayın ve geri yazın.

Mevcut kaynak Yapay Zeka dalına alınmadan düzenlenmeye çalışıldı

Yapay Zeka dalları boş başlar.

Çözüm: Mevcut uç noktayı veya şemayı önce pick-to ile dala alın.

Yapay Zeka dalı için yanlış --from değeri kullanıldı

Kaynak ana dal veya sprint dalı olmalıdır; genel dal olmamalıdır.

Çözüm: branch create komutunda geçerli kaynak dalı kullanın.

Doğrulama atlandı

cli-schema validate, hatalı biçimlendirilmiş yükleri yerelde yakalar.

Çözüm: Her update işleminden önce doğrulama komutunu çalıştırın.

Bozucu değişiklik sessizce birleştirildi

Yeni gerekli alanlar, kaldırılan alanlar veya sıkılaştırılan türler istemcileri bozabilir.

Çözüm: Bozucu değişiklik sınıflandırmasını zorunlu bir insan onay adımı yapın.

Sıkça Sorulan Sorular

Aracının ana dalı doğrudan düzenlemesine izin verebilir miyim?

Harici Yapay Zeka Düzenleme İzinlerini etkinleştirerek izin verebilirsiniz. Ancak Yapay Zeka dalı ile başlamak daha güvenlidir; siz onaylayana kadar ana dala hiçbir değişiklik ulaşmaz.

branch merge ve merge-request arasındaki fark nedir?

branch merge, değişikliği hemen yazar ve her iki dalda da doğrudan düzenleme izni gerektirir. merge-request, incelenebilir bir istek açar ve ana dal korumalıysa doğru yaklaşımdır.

Aracının Apidog masaüstü uygulamasına ihtiyacı var mı?

Hayır. CLI bağımsız çalışır. Masaüstü uygulaması yalnızca Harici Yapay Zeka Düzenleme İzinleri ayarını açmak veya kapatmak için gereklidir.

Aracının alan adı uydurmadığından nasıl emin olabilirim?

cli-schema get → validate döngüsünü kullanın. Uydurulmuş veya geçersiz alanlar içeren yükler, projeye ulaşmadan önce yerelde doğrulamadan geçemez.

Özet

Bir aracının API spesifikasyonunuzu güvenli biçimde güncellemesi için üç temel kuralı uygulayın:

1. İzole bir Yapay Zeka dalında çalışın.
2. Her güncellemeyi tam bir oku-değiştir-yaz işlemi olarak ele alın.
3. Birleştirmeden önce insan incelemesi ve bozucu değişiklik kontrolü yapın.

Apidog CLI bu akışın tamamını komutlarla destekler. Böylece düzenleme, doğrulama, inceleme ve geri alma süreçleri betiklenebilir ve denetlenebilir hâle gelir.

Yapay Zeka dalını oluşturun, aracıya tam nesne güncelleme ve bozucu değişiklik kontrol kurallarını verin. Böylece API spesifikasyonu bakımı ertelenen zahmetli bir iş olmaktan çıkar, inceleyip onayladığınız bir değişiklik setine dönüşür.

CLI'ı edinmek için Apidog'u indirin. Yazma ve bakım döngüsünü tamamlamak için bunu bir aracının dokümanlarınızı oluşturmasına izin verme yaklaşımıyla birleştirin.