Bir API spesifikasyonunu elle düzenlemek zahmetli bir iştir. Bir alanı yeniden adlandırmak, bir enum değeri eklemek, gerekli bir bayrağı sıkılaştırmak. Her değişiklik küçük olsa da, her birinin referans veren uç noktaları bozmadan doğru yere inmesi gerekir. Bu hassas, mekanik ve tam olarak bir yapay zeka aracısına vereceğiniz türden bir görevdir, tabii tüm şemayı bozmayacağına güvenebilseniz.
Yapabilirsiniz. Apidog CLI, bir aracıya bir spesifikasyonu sorumlu bir şekilde değiştirmek için ihtiyaç duyduğu her şeyi verir: her yazmadan önce şema doğrulama, üzerinde çalışılacak izole bir dal ve sizin incelemeniz için bir birleştirme isteği.
Bu, bir aracının API dokümantasyonu oluşturmasına izin vermenin mutasyon eşliğidir. Oluşturma ekleyicidir ve düşük risklidir; mevcut bir sözleşmeyi güncellemek ise koruyucu önlemlerin önemli olduğu yerdir, bu nedenle bu kılavuzun çoğu, hiçbir şeyi bozmadan bunu yapma hakkındadır.
CLI'da "spesifikasyonu güncellemek" ne anlama geliyor
Apidog'daki spesifikasyonunuz, bir projedeki uç noktalar ve veri şemaları kümesidir. Onu güncellemek şu üç komuttan birini ifade eder:
endpoint update: bir yolu, bir parametreyi, bir yanıtı değiştirin.schema update: uç noktaların referans verdiği bir veri modelini değiştirin.import: projeyle uzlaştırmak için tamamen yeni bir OpenAPI dosyasını getirin.
Bir aracıyı bunlardan herhangi birine yönlendirmeden önce, anlamanız gereken iki davranış vardır, çünkü bunları yanlış yapmak bir spesifikasyonun zarar görmesine neden olur. Birincisi bir izin modelidir ve ikincisi de verileri sessizce silen bir tuzaktır.
Başınızı ağrıtacak tuzak: güncelleme tam bir değiştirmedir
Bu, aracınıza öğretmeniz gereken en önemli tek şeydir. CLI'ın update komutları JSON Patch değildir. Sağladığınız alanları doğrudan gönderirler; dizi öğelerini kimliğe göre birleştirmezler. Yalnızca bir parametreyi değiştirmek amacıyla kısmi bir parameters dizisiyle bir güncelleme gönderirseniz, o parametreyi düzenlemezsiniz. Tüm diziyi yalnızca gönderdiğinizle değiştirirsiniz ve geri kalanı kaybolur.
Doğru sıra her zaman tam nesne üzerinde oku-değiştir-yaz şeklindedir:
# 1. Mevcut kaynağın tamamını alın
apidog endpoint get <endpointId> --project <projectId>
# 2. Tam yapıyı yerel olarak düzenleyin (değiştirmediğiniz her alanı saklayın)
# 3. Tüm nesneyi şemaya 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
Bunu aracının talimatlarına açık bir şekilde koyun: update komutuna asla kısmi bir nesne göndermeyin; her zaman tam kaynağı getirin, değiştirin ve tamamını geri gönderin. get adımını atlayan bir aracı, alanları sessizce düşürecektir. Önce cli-schema validate komutunu çalıştıran bir aracı, hatalarını projeye ulaşmadan önce yakalar.
Güvenli yol: aracının bir yapay zeka dalında çalışmasına izin verin
Aracıya ana dalınızda doğrudan düzenleme izni verebilirsiniz. Başlangıçta bunu yapmayın. Apidog'un bu amaç için özel olarak tasarlanmış bir izolasyon mekanizması olan Yapay Zeka dalı vardır: bir aracı, kaynak dala dokunmadan kaynakları değiştirir ve siz söyleyene kadar hiçbir şey geri birleşmez. Bunu API spesifikasyonunuz için bir çekme isteği olarak düşünün.
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"
Adlandırma kuralı ai/YYYYAAgg-kaynak-özellikten şeklindedir, böylece dalın kökeni ve amacı bir bakışta anlaşılır olur. --from değeri ana dalınız veya normal bir sprint dalı olmalı, genel bir dal olmamalıdır. Pratik bir ayrıntı: kaynağından farkı olmayan bir Yapay Zeka dalı 24 saat sonra otomatik olarak arşivlenir, böylece terk edilmiş deneyler kendiliğinden temizlenir.
Adım 2: Aracının düzenleyeceği kaynakları içeri aktarın
Bir Yapay Zeka dalı boş başlar. Kaynak dalı otomatik olarak klonlamaz. Aracı, mevcut bir uç noktayı veya şemayı düzenleyebilmesi için, o kaynağı pick-to ile dala çekmelidir:
apidog branch pick-to --project <projectId> --type ai \
--from main --to "ai/20260713-from-main-refund-fields" \
--endpoint-ids <ids>
Aracının dal üzerinde oluşturduğu yeni kaynaklar buna ihtiyaç duymaz; yalnızca değiştirmeyi veya silmeyi amaçladığı mevcut kaynaklar için gereklidir. Bu, insanların unuttuğu adımdır: bunu atlarsanız, aracının boş bir dalı olur ve düzenleyecek hiçbir şeyi kalmaz.
Adım 3: Aracının değişikliği yapmasına izin verin
Şimdi aracı, daha önce bahsedilen oku-değiştir-yaz döngüsünü çalıştırır, ancak --branch Yapay Zeka dalını işaret eder. Her düzenleme sınırlıdır:
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
Ana dalınız bu süre boyunca hiç dokunulmamış kalır. Eğer aracı bir şeyi yanlış yaparsa, etki alanı bir kerelik kullanılıp atılacak bir daldır.
Adım 4: İnceleyin, sonra birleştirin
Yapay Zeka dalı değişiklikleri asla otomatik olarak geri yazılmaz. Aracı bittiğinde, ne olacağına siz karar verirsiniz. Eğer hedef korunuyorsa, doğrudan birleştirmek yerine bir 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 onaylanmış değişiklik ana dala iner. CLI'dan doğrudan birleştirme, hem kaynak hem de hedef dal üzerinde doğrudan düzenleme izni gerektirir; ana dal korunuyorsa, merge-request kullanmayı ve Apidog istemcisinde onaylamayı tercih edin.
Uygulamalı bir örnek: bir alanı güvenli bir şekilde yeniden adlandırma
Soyut kurallar onaylaması kolay, uygulaması zordur. İşte somut bir örnek. Diyelim ki Refund veri modelindeki amount alanını amountCents olarak yeniden adlandırmak istiyorsunuz, çünkü tam sayı kuruşlara geçiyorsunuz.
Aracıya şunu söylersiniz: "Refund şemasındaki amount alanını amountCents olarak yeniden adlandır ve bunu bir tam sayı yap." Kurallarına uyarak aracı:
# 1. Yapay Zeka dalındaki TAM mevcut şemayı getirin
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"
Tam nesneyi geri alır ve dokunmadığı her alanı koruyarak tüm jsonSchema'yı düzenler:
{
"name": "Refund",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amountCents"],
"properties": {
"orderId": { "type": "string" },
"amountCents": { "type": "integer" },
"reason": { "type": "string" }
}
}
}
Neyin olmadığına dikkat edin: sadece değişen tek özelliği göndermedi. orderId ve reason sağlam kalacak şekilde tüm şemayı gönderdi, çünkü update değiştirir. Ardından:
# 2. Tam nesneyi doğrulayın
apidog cli-schema validate schema-create --file ./refund-full.json
# 3. Yapay Zeka dalına geri yazın
apidog schema update <refundSchemaId> --project $PID \
--branch "ai/20260713-from-main-refund-fields" --file ./refund-full.json
Yapay Zeka dalı farkını incelersiniz (bir alan yeniden adlandırılmış, başka hiçbir şeye dokunulmamış) ve birleştirirsiniz. Disiplinin tamamı budur: tam nesne, doğrulanmış, bir dalda, incelemeden sonra birleştirilmiş.
Birleştirmeden önce bozucu değişiklikleri işaretleyin
Gerekli bir alanı yeniden adlandırmak bozucu bir değişikliktir: amount gönderen herhangi bir istemci artık doğrulamayı geçemeyecektir. İyi bir aracı talimat seti, modelin sessizce birleştirmek yerine bunu söylemesini sağlar. Bunu aracının kurallarına ekleyin:
Herhangi bir spesifikasyon değişikliğini birleştirmeden önce, onu sınıflandırın:
- Bozucu olmayan (yeni isteğe bağlı alan, yeni uç nokta, gevşetilmiş kısıtlama) → özetleyin ve birleştirme isteğine devam edin.
- Bozucu (yeniden adlandırılmış/kaldırılmış alan, yeni gerekli alan, sıkılaştırılmış tür) → DUR.
Bozucu değişikliği ve etkilenen uç noktaları bildirin ve açık insan onayı bekleyin.
Yapay Zeka dalı, bunun uygulanmasını güvenli hale getiren şeydir: hiçbir şey otomatik olarak birleşmediği için, "dur ve bildir" gerçek bir kontrol noktasıdır, zaten gerçekleşmiş bir yazmaya karşı bir yarış değildir.
Bunun yerine bir OpenAPI dosyasından güncelleme
Bazen değişiklik zaten koddan oluşturulmuş, başka bir yerde düzenlenmiş veya başka bir ekip tarafından size verilmiş bir OpenAPI dosyası olarak mevcuttur. Alanları tek tek yeniden düzenlemek yerine, aracı dosyayı projeyle uzlaştırmak için içeri aktarabilir:
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 daha fazlasını kabul eder. Gelen spesifikasyon değişikliklerini ana dala ulaşmadan önce inceleyebilmek için önce bir Yapay Zeka dalına karşı çalıştırın. Birleştirmeden sonra, sonucu onaylamak için uzlaştırılmış spesifikasyonu dışa aktarın:
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Bu yol, doğruluk kaynağının Apidog dışında olduğu ve onu senkronize ettiğiniz durumlarda en iyisidir. Alan bazında update yolu, Apidog'un doğruluk kaynağı olduğu ve cerrahi bir değişiklik yaptığınız durumlarda en iyisidir.
Aracı yanlış yaptığında: geri alma
Bir Yapay Zeka dalında çalışmanın nedeni, hataları geri almanın ucuz olmasıdır. Aracı, istemediğiniz bir değişiklik üretirse, onu asla birleştirmediniz, bu yüzden ana dal zaten doğrudur. Sadece dalı arşivleyin ve devam edin:
apidog branch archive "ai/20260713-from-main-refund-fields" --project <projectId> --type ai
Kabul edilmiş bir farkı olmayan bir Yapay Zeka dalı 24 saat sonra otomatik olarak arşivlendiği için, unutulmuş bir deney bile kendini temizler. Bunu, kötü bir update'in hemen canlı olduğu ve tek çarenizin geri dönüşüm kutusu veya elle geri alma olduğu, ana dalı doğrudan düzenleyen bir aracıyla karşılaştırın. Dal bürokrasi değildir; o bir geri alma düğmesidir.
İzinler hakkında bir not
Eğer bir update veya import engellenmiş olarak geri dönerse, projenin Harici Yapay Zeka Düzenleme İzinleri kapalıdır. Bu bilinçli bir engeldir ve yukarıdaki Yapay Zeka dalı akışı bunun cevabıdır: aracı izole bir dalı düzenler ve birleştirmeyi siz onaylarsınız. Doğrudan düzenlemelere izin vermek isterseniz, anahtar Proje Ayarları → Özellik Ayarları → Yapay Zeka Özellik Ayarları (Apidog istemcisi 2.8.32+) içinde bulunur. Bir aracı bir izin duvarına çarptığında, sessizce bir geçici çözüm bulmasına izin vermeyin; seçimi bir insana bildirin.
Yaygın aksaklıklar
Kısmi güncelleme alanları sildi. En zararlı ve en yaygın hata. update değiştirir; birleştirmez. Tam nesneyi getirin, bütün olarak düzenleyin, doğrulayın, sonra yazın. Bir alan kaybolduysa, aracı kısmi bir yük gönderdi.
Mevcut bir kaynağı bir Yapay Zeka dalında içeri aktarmadan düzenleme. Dal boş başlar. Önce kaynağı pick-to ile içeri alın, yoksa aracının düzenleyecek hiçbir şeyi olmaz.
Yapay Zeka dalı için yanlış --from. Kaynak ana veya bir sprint dalı olmalı, asla genel bir dal olmamalıdır. Bunu yanlış yaparsanız branch create komutu hata verecektir.
Doğrulamayı atlama. cli-schema validate makinenizde hatalı biçimlendirilmiş bir yükü yakalar. Doğrulamadan yazan bir aracı, bir yazım hatasını başarısız bir API çağrısına veya daha kötüsü, kötü bir birleştirmeye dönüştürür.
Bozucu bir değişikliği sessizce birleştirme. Önce sınıflandırma kuralı olmadan, bir aracı gerekli bir alanı memnuniyetle yeniden adlandırır ve birleştirir. Bozucu değişiklik tespitini açık bir kontrol noktası haline getirin.
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 yapabilirsiniz, ancak bir Yapay Zeka dalında başlamak daha güvenlidir: siz birleştirmeyi onaylayana kadar ana dala hiçbir şey düşmez. Doğrudan düzenlemeleri düşük riskli, yüksek güvenli otomasyon için saklayın.
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, ana dal korunduğunda doğru seçimdir.
Aracının Apidog masaüstü uygulamasına ihtiyacı var mı? Hayır, CLI bağımsızdır. Uygulama yalnızca, tek seferlik bir yapılandırma olan Harici Yapay Zeka Düzenleme İzinleri ayarını açıp kapamak için önemlidir.
Aracının bir alan adını uydurmadığından nasıl emin olabilirim? cli-schema get → validate döngüsü koruyucu önlemdir. Uydurulmuş bir alana sahip bir yük, projeye ulaşmadan önce yerel olarak doğrulamayı geçemez.
Özetliyor
Bir aracının API spesifikasyonunuzu güncellemesine izin vermek üç şey doğru olduğunda güvenlidir: izole bir Yapay Zeka dalında çalışır, her güncellemeyi bir yama yerine tam bir oku-değiştir-yaz olarak ele alır ve bir insan birleştirmeyi onaylar. Apidog CLI size bu üçünü de komut olarak verir, bu da tüm döngünün (düzenle, doğrula, incele) betiklenebilir ve denetlenebilir olduğu anlamına gelir ve kötü bir değişiklik bir archive komutu kadar uzaktadır.
Yapay Zeka dalını kurun, aracıya oku-değiştir-yaz kuralını ve bozucu değişiklik kontrol noktasını verin; böylece spesifikasyon bakımı, sürekli ertelediğiniz zahmetli bir iş yerine onayladığınız bir fark haline gelir. CLI'ı edinmek için Apidog'u indirin ve tüm yazma ve bakım döngüsünü kapsamak için bunu bir aracının dokümanlarınızı oluşturmasına izin verme ile birleştirin.