Claude Code kullanarak davranıştan OpenAPI nasıl oluşturulur, bunu API uygulamanızla nasıl karşılaştırırsınız ve basit istemci/sunucu doğrulama örnekleri nasıl oluşturulur öğrenin.
OpenAPI sözleşmesi, API'nizin paylaşılmış bir tanımıdır: hangi uç noktalar var, neler gönderiliyor, ne dönüyor ve hatalar nasıl görünüyor. Sunucu ile onu çağıran her şey (web uygulaması, mobil uygulama veya başka bir servis) arasındaki anlaşmadır.
Sorun sapma (drift). Çalışan API değişir ama spec değişmez. Ya da spec gerçeğin üstünü "daha temiz" göstermek için düzenlenir; bu arada uygulama garip alanlar döndürmeye, eksik durum kodlarına veya tutarsız hata şekillerine devam eder. Zamanla insanlar OpenAPI dosyasına güvenmeyi bırakır ve o dosya herkesin görmezden geldiği başka bir dokümana dönüşür.
Sapma genellikle normal baskılardan kaynaklanır: hızlı bir düzeltme spec güncellenmeden yayımlanır, yeni bir opsiyonel alan "geçici" eklenir, sayfalama evrilir veya ekipler farklı "gerçeklik kaynaklarını" (backend kodu, bir Postman koleksiyonu ve bir OpenAPI dosyası) günceller.
Dürüst tutmak, spec’in gerçek davranımla eşleşmesi demektir. API bazen bir çatışma için 409 döndürüyorsa, bu sözleşmeye ait olmalıdır. Bir alan nullable ise bunu belirtin. Kimlik doğrulama gerekiyorsa, belirsiz bırakmayın.
İyi bir iş akışı size şunları sağlar:
Son nokta önemlidir çünkü bir sözleşme ancak uygulandığında yardımcı olur. Dürüst bir spec ve tekrarlanabilir kontroller "API dokümantasyonu"nu ekiplerin güvenebileceği bir şeye dönüştürür.
Koda bakarak veya rotaları kopyalayarak başlarsanız, OpenAPI bugün var olanı, istemeyeceğiniz tuhaflıklar dahil olmak üzere tarif eder. Bunun yerine, çağıran için API'nin ne yapması gerektiğini tanımlayın, sonra spec'i uygulamanın buna uyup uymadığını doğrulamak için kullanın.
YAML veya JSON yazmadan önce, her uç nokta için küçük bir gerçek seti toplayın:
Davranışı örnekler halinde yazın. Örnekler sizi spesifik olmaya zorlar ve tutarlı bir sözleşme taslağı hazırlamayı kolaylaştırır.
Bir Tasks API için mutlu yol örneği şöyle olabilir: “title ile bir görev oluştur ve id, title, status ve createdAt dön.” Yaygın hataları ekleyin: “title eksikse 400 döner {error:"title is required"}” ve “auth yoksa 401 döner.” Kenar durumları biliyorsanız bunları da dahil edin: tekrar eden başlıklar izinli mi, bir görev ID'si yoksa ne olur gibi.
Kuralları kod detaylarına bağlı olmayan basit cümleler halinde yakalayın:
title zorunlu ve 1-120 karakter arası.”limit ayarlanmadıkça (maks 200).”dueDate ISO 8601 date-time.”Son olarak v1 kapsamınızı kararlaştırın. Emin değilseniz v1'i küçük ve net tutun (create, read, list, update status). Arama, toplu güncellemeler ve karmaşık filtreleri daha sonra saklayın ki sözleşme inandırıcı kalsın.
Claude Code’dan spec yazmasını istemeden önce davranış notlarını küçük, tekrarlanabilir bir formatta yazın. Amaç, modelin tahminle doldurmasını kazara zorlaştırmaktır.
İyi bir şablon, gerçekten kullanacağınız kadar kısa ama iki kişinin aynı uç noktayı benzer şekilde tanımlamasını sağlayacak kadar tutarlı olmalıdır. Odaklanın: API ne yapıyor, nasıl uygulandığı değil.
Bir uç nokta için bir blok kullanın:
METHOD + PATH:
Purpose (1 sentence):
Auth:
Request:
- Query:
- Headers:
- Body example (JSON):
Responses:
- 200 OK example (JSON):
- 4xx example (status + JSON):
Edge cases:
Data types (human terms):
En az bir somut istek ve iki yanıt yazın. Durum kodlarını ve gerçek alan adlarıyla gerçekçi JSON gövdelerini içeren örnekler ekleyin. Bir alan opsiyonelse, bir örnekte eksik olduğunu gösterin.
Kenar durumlarını açıkça belirtin. Buralar genelde spec’in daha sonra sessizce yanlış olduğu yerlerdir çünkü herkes farklı varsayım yapmıştır: boş sonuçlar, geçersiz ID’ler (400 vs 404), çoğaltmalar (409 vs idempotent davranış), doğrulama hataları ve sayfalama limitleri.
Ayrıca şemaları düşünmeden önce veri tiplerini insan dilinde not edin: stringler vs sayılar, date-time formatları, boolean ve enumlar (izin verilen değerler listesi). Bu, güzel görünen ama gerçek yüklerle eşleşmeyen bir şemayı engeller.
Claude Code’a onu dikkatli bir kâtip gibi davranın. Davranış notlarınızı ve OpenAPI'nin nasıl şekillenmesi gerektiğine dair katı kuralları verin. Sadece “OpenAPI spec yaz” derseniz, genelde tahminler, tutarsız isimlendirme ve eksik hata durumları alırsınız.
Davranış notlarınızı yapıştırın, sonra sıkı bir talimat bloğu ekleyin. Pratik bir prompt şöyle görünür:
You are generating an OpenAPI 3.1 YAML spec.
Source of truth: the behavior notes below. Do not invent endpoints or fields.
If anything is unclear, list it under ASSUMPTIONS and leave TODO markers in the spec.
Requirements:
- Include: info, servers (placeholder), tags, paths, components/schemas, components/securitySchemes.
- For each operation: operationId, tags, summary, description, parameters, requestBody (when needed), responses.
- Model errors consistently with a reusable Error schema and reference it in 4xx/5xx responses.
- Keep naming consistent: PascalCase schema names, lowerCamelCase fields, stable operationId pattern.
Behavior notes:
[PASTE YOUR NOTES HERE]
Output only the OpenAPI YAML, then a short ASSUMPTIONS list.
Taslağı aldıktan sonra önce ASSUMPTIONS’ı tarayın. Burada dürüstlük kazanılır veya kaybedilir. Doğru olanları onaylayın, yanlışları düzeltin ve güncellenmiş notlarla yeniden çalıştırın.
İsimlendirmeyi tutarlı tutmak için, baştan kuralları belirtin ve ona bağlı kalın. Örneğin: kararlı bir operationId deseni, sadece isimlerden oluşan tag isimleri, tekil şema isimleri, paylaşılan bir Error şeması ve her yerde kullanılan tek bir auth şeması adı.
Koder.ai gibi sohbetle çalışan bir çalışma alanında çalışıyorsanız, YAML'i gerçek bir dosya olarak erken kaydetmek ve küçük difler halinde yinelemek işe yarar. Hangi değişikliklerin onaylanmış davranış kararlarından geldiğini ve hangilerinin modelin tahminlerinden geldiğini görebilirsiniz.
Her şeyi production ile karşılaştırmadan önce OpenAPI dosyasının dahili olarak tutarlı olduğundan emin olun. Bu, isteksiz düşünceleri ve belirsiz ifadeleri yakalamanın en hızlı yoludur.
Her uç noktayı istemci geliştiricisiymiş gibi okuyun. Bir çağıranın ne göndermesi gerektiğine ve ne alabileceğine odaklanın.
Pratik bir inceleme turu:
Hata yanıtları özel ilgi ister. Tek bir paylaşılan şekil seçin ve her yerde tekrar kullanın. Bazı ekipler çok basit tutar ({ error: string }), diğerleri daha detaylı bir obje kullanır ({ error: { code, message, details } }). Her ikisi de çalışabilir, ama endpointler ve örneklerde karışıklığa yol açmayın. Karıştırırsanız istemci kodu özel vakalarla dolar.
Kısa bir mantık testi yardımcı olur. Eğer POST /tasks title gerektiriyorsa, şema bunu required olarak işaretlemeli, hata yanıtı gerçekten döndüğünüz hata gövdesini göstermeli ve operasyon auth gerektirip gerektirmediğini açıkça belirtmelidir.
Spec, amaçlanan davranış gibi okunurken, çalışan API bugünün kullanıcılarının deneyimidir. Amaç uyuşmazlıkları erken ortaya çıkarmak ve her birine karar vermektir.
İlk geçişte gerçek istek/yanıt örnekleri genelde en basit seçenektir. Loglar ve otomatik testler de işe yarar, eğer güvenilirlerse.
Yaygın uyumsuzluklara dikkat edin: bir yerde var olan ama diğer yerde olmayan uç noktalar, alan isimleri veya şekil farklılıkları, durum kodu farkları (200 vs 201, 400 vs 422), dokümante edilmemiş davranışlar (sayfalama, sıralama, filtreleme) ve auth farklılıkları (spec public diyor ama kod token istiyor).
Örnek: OpenAPI POST /tasks için 201 ve {id,title} diyor. Çalışan API'yi çağırdığınızda 200 ve {id,title,createdAt} alıyorsunuz. Bu, spec’ten SDK üretirken "yeterince yakın" sayılmaz.
Herhangi bir şeyi değiştirmeden önce uyuşmazlıkları çözme tavsiyeleri:
Her değişikliği küçük ve gözden geçirilebilir tutun: bir uç nokta, bir yanıt, bir şema düzeltmesi. İncelemek ve yeniden test etmek daha kolay olur.
Güvendiğiniz bir spec’e sahip olduğunuzda, bunu küçük doğrulama örneklerine dönüştürün. Bu, sapmanın geri gelmesini önler.
Sunucuda doğrulama, sözleşmeye uymayan bir isteği hızlıca reddetmek ve net bir hata döndürmek demektir. Bu verilerinizi korur ve hataları bulmayı kolaylaştırır.
Sunucu doğrulama örneklerini üç parça halinde ifade etmek basittir: girdi, beklenen çıktı ve beklenen hata (tam metin değil, bir hata kodu veya mesaj paterni).
Örnek (sözleşme titleın gerekli ve 1-120 karakter olduğunu söylüyor):
{
"name": "Create task without title returns 400",
"request": {"method": "POST", "path": "/tasks", "body": {"title": ""}},
"expect": {"status": 400, "body": {"error": {"code": "VALIDATION_ERROR"}}}
}
İstemcide doğrulama, sunucu farklı bir şekil döndürmeye başlarsa veya gerekli bir alan kaybolursa bunu tespit etmektir.
İstemci kontrollerini, gerçekten güvendiğiniz şeylere odaklayın: örneğin “bir görev id, title, status içerir.” Tüm opsiyonel alanları veya sıralamayı zorlamayın. Kırılmalar için fail olacak, zararsız eklemeler için değil.
Okunabilir testler için birkaç yönerge:
Koder.ai kullanıyorsanız bu örnek durumları OpenAPI dosyanızın yanına koyabilir, davranış değiştikçe aynı gözden geçirme içinde güncelleyebilirsiniz.
Küçük bir API düşünün: POST /tasks bir görev oluşturur, GET /tasks görevleri listeler ve GET /tasks/{id} tek bir görevi döndürür.
Önce bir uç nokta için birkaç somut örnek yazın, sanki bir testçiye açıklıyormuş gibi.
POST /tasks için amaçlanan davranış şunlar olabilir:
{ "title": "Buy milk" } gönderin ve yeni görev nesnesiyle 201 dönün; nesnede id, title ve done:false olsun.{} gönderildiğinde 400 dönsün { "error": "title is required" } gibi.{ "title": "x" } (çok kısa) gönderildiğinde 422 dönsün { "error": "title must be at least 3 characters" } gibi.Claude Code taslağı oluşturduğunda, bu uç nokta için snippet şema, durum kodları ve gerçekçi örnekleri yakalamalıdır:
paths:
/tasks:
post:
summary: Create a task
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTaskRequest'
examples:
ok:
value: { "title": "Buy milk" }
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
examples:
created:
value: { "id": "t_123", "title": "Buy milk", "done": false }
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missingTitle:
value: { "error": "title is required" }
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tooShort:
value: { "error": "title must be at least 3 characters" }
Yaygın bir uyumsuzluk ince bir farktır: çalışan API 201 yerine 200 döndürüyor, veya { "taskId": 123 } yerine { "id": "t_123" } dönüyor. Bu tür "neredeyse aynı" farklar jenerik istemcileri bozar.
Bunu düzeltmek için bir gerçeği seçin. Eğer amaçlanan davranış doğruysa, uygulamayı 201 ve kararlaştırılmış Task şekline dönecek şekilde değiştirin. Üretim davranışı zaten güveniliyorsa, spec’i (ve davranış notlarını) gerçeğe göre güncelleyin, sonra istemcilerin şaşırmaması için eksik doğrulama ve hata yanıtlarını ekleyin.
Bir sözleşme, kuralları tanımlamayı bıraktığında ve API’nizin bir iyi gününün çıktısını tarif etmeye başladığında sahte olur. Basit bir test: yeni bir implementasyon bu spec’e uymak için bugünkü tuhaflıkları kopyalamadan geçebilir mi?
Aşırı uyum (overfitting) bir tuzaktır. Bir yanıtı alıp onu kanun haline getirirsiniz. Örnek: API şu an her görev için dueDate: null döndürüyor, spec de alanın hep nullable olduğunu söyler. Oysa gerçek kural belki "status scheduled olduğunda gerekli"dir. Sözleşme kuralı ifade etmeli, sadece mevcut veri setini değil.
Hatalar dürüstlüğün sık kırıldığı yerdir. Başarı yanıtlarını spec’lemek cazip çünkü temiz görünürler, ama istemciler temelde şu bilgilere ihtiyaç duyar: token eksikse 401, yasak ise 403, bilinmeyen ID için 404 ve tutarlı bir doğrulama hatası (400 veya 422).
Diğer sorunlu kalıplar:
taskId bir route’da, id başka yerde; ya da priority bir yanıtta string, diğerinde sayı olur).string olur, her şey opsiyonel olur).İyi bir sözleşme test edilebilir olandır. Spec’ten başarısız bir test yazamıyorsanız, henüz dürüst değil demektir.
Bir OpenAPI dosyasını başka bir ekibe vermeden önce "birisi sizin aklınızı okumadan kullanabilir mi?" sorusunu sorun.
Örneklerle başlayın. Bir spec geçerli olabilir ama her istek ve yanıt soyutsa işe yaramazdır. Her operasyon için en az bir gerçekçi istek örneği ve bir başarı yanıtı ekleyin. Hatalar için de (auth, doğrulama) birer örnek genelde yeterlidir.
Sonra tutarlılığı kontrol edin. Bir uç nokta { "error": "..." } dönerken diğeri { "message": "..." } dönerse istemci tarafında dallanma mantığı çoğalır. Tek bir hata şekli seçin ve tekrar kullanın; ayrıca durum kodlarını öngörülebilir yapın.
Kısa bir kontrol listesi:
Pratik bir numara: bir uç nokta seçin, hiç API görmemiş gibi davranın ve cevaplayın: “Ne gönderirim, ne alırım ve ne kırılır?” Eğer OpenAPI bu soruyu açıkça cevaplamıyorsa, hazır değildir.
Bu iş akışı düzenli çalıştığında kazandırır, sadece sürüm öncesi telaşta değil. Basit bir kural seçin ve ona bağlı kalın: bir uç nokta değiştiğinde çalıştırın ve spec yayımlamadan önce yeniden çalıştırın.
Sahipliği basit tutun. Uç noktayı değiştiren kişi davranış notlarını ve spec taslağını günceller. İkinci bir kişi “spec vs uygulama” difini kod incelemesi gibi gözden geçirir. QA veya destek ekipleri iyi gözden geçiriciler olabilir çünkü belirsiz yanıtları ve kenar durumlarını çabucak fark ederler.
Sözleşme düzenlemelerini kod düzenlemeleri gibi ele alın. Eğer sohbet tabanlı bir oluşturucu kullanıyorsanız (ör. Koder.ai), riskli düzenlemelerden önce anlık görüntü almak ve gerektiğinde rollback yapmak iterasyonu güvenli kılar. Koder.ai ayrıca kaynak kodu dışa aktarmayı destekler, bu da spec ve uygulamayı aynı repoda yan yana tutmayı kolaylaştırır.
Yavaşlatmadan işe yarayan bir rutin:
Sonraki adım: zaten var olan bir uç noktayı seçin. 5-10 satır davranış notu yazın (girdiler, çıktılar, hata durumları), bu notlardan bir OpenAPI taslağı üretin, doğrulayın, sonra çalışan implementasyonla karşılaştırın. Bir uyuşmazlık düzeltin, yeniden test edin ve tekrarlayın. Bir uç noktadan sonra alışkanlık yerleşmeye başlar.
OpenAPI drift, gerçekte çalıştırdığınız API ile paylaşılan OpenAPI dosyasının artık eşleşmemesi anlamına gelir. Spec yeni alanları, durum kodlarını veya kimlik doğrulama kurallarını eksik tutuyor olabilir ya da “ideal” davranışı tanımlıyor olabilir ama sunucu buna uymuyor.
Bunun önemi şu: istemciler (uygulamalar, diğer servisler, jenerik SDK’lar, testler) sözleşmeye göre hareket eder; gerçek davranışla uyumsuzluk hatalara ve güven kaybına yol açar.
Client tarafında hatalar rastgele ve zor ayıklanır hale gelir: mobil uygulama 201 beklerken 200 alır, bir SDK yanıtı deserialize edemez çünkü alan yeniden adlandırılmıştır, veya hata işleme tutarsız hata şekilleri yüzünden başarısız olur.
Hiçbir şey çökmediğinde bile ekipler spec’e güvenmeyi bırakır ve bu erken uyarı sistemini kaybetmenize neden olur.
Çünkü kod mevcut davranışı ve içindeki kazara oluşmuş tuhaflıkları yansıtır; uzun vadede garanti etmek istemeyeceğiniz garip durumlar spec’e girer.
Daha iyi bir varsayılan: önce beklenen davranışı yazın (girdiler, çıktılar, hatalar), sonra uygulamanın buna uyduğunu doğrulayın. Bu, uygulamayı doğrulamak yerine sadece bugünkü rotaların fotoğrafını çekmekten daha sağlam bir sözleşme sağlar.
Her uç nokta için şu bilgileri yakalayın:
Somut bir istek ve iki yanıt yazabiliyorsanız, dürüst bir spec taslağı için genelde yeterlidir.
Bir hata gövdesi biçimi seçin ve tüm yerlerde tekrar kullanın.
Basit bir varsayılan ya şudur:
{ "error": "message" }, veya{ "error": { "code": "...", "message": "...", "details": ... } }Sonra bunu tüm uç noktalar ve örnekler boyunca tutarlı kullanın. Tutarlılık, karmaşıklıktan daha önemlidir çünkü istemciler bu şekli sabitleyecektir.
Claude Code’a davranış notlarınızı ve sahte alan üretmemesi için katı kuralları verin. Pratik bir talimat seti:
TODO ekleyin ve bunları ASSUMPTIONS altında listeleyin.”Error gibi) ekleyin ve referans verin.”Oluştuktan sonra önce ASSUMPTIONS bölümünü inceleyin; modelin tahminleri orada başlarsa sorun orada düzeltilir.
Önce spec’in kendisini doğrulayın:
201)Bu, üretim davranışına bakmadan önce “istekli” OpenAPI dosyalarını yakalamaya yardımcı olur.
Çalışan API şu anda kullanıcıların deneyimlediği şey olduğundan, uyuşmazlıkları madde madde ele alın:
Değişiklikleri küçük tutun (bir uç nokta veya bir yanıt), böylece hızlıca yeniden test edebilirsiniz.
Sunucu tarafında doğrulama, sözleşmeye uymayan istekleri hızlıca reddetmek ve tutarlı bir hata dönmektir (durum + hata kodu/şekli).
İstemci tarafında doğrulama, sunucu beklenmeyen bir şekil döndüğünde veya gerekli bir alan kaybolduğunda bunu erken tespit etmektir:
Tüm isteğe bağlı alanları zorlamayın; istemcinin gerçekten güvendiği şeylere odaklanın ki testler yalnızca kırılmalar üzerine fail olsun.
Pratik bir rutin:
Koder.ai kullanıyorsanız OpenAPI dosyasını kodla yan yana tutabilir, riskli değişikliklerden önce anlık görüntü alabilir ve gerekirse rollback yapabilirsiniz.