Davranıştan OpenAPI oluşturun — Claude Code ile dürüstçe

Neden OpenAPI sözleşmeleri sapar (ve neden önemlidir)

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:

• Hem amaçlanan hem de gözlemlenen davranışı yansıtan bir OpenAPI dosyası
• İstemciler kırılmadan önce sapmayı erken yakalayacak basit kontroller
• Kod tabanınıza kopyalayabileceğiniz somut istemci ve sunucu doğrulama örnekleri

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 değil, amaçlanan davranışa odaklanarak başlayın

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:

• Ne yaptığı (method ve path)
• Neleri kabul ettiği (headers, query, path parametreleri, body)
• Ne döndürdüğü (başarı durum kodu, yanıt şekli, önemli başlıklar)
• Neler başarısız olabilir (olası hatalar, durum kodları, hata gövdesi şekli)
• Kim çağırabilir (auth ve roller, ilgiliyse)

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ı.”
• “List 50 öğeye kadar döner, limit ayarlanmadıkça (maks 200).”
• “dueDate ISO 8601 date-time.”
• “Yazma uç noktaları bir kullanıcı tokeni gerektirir.”

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.

Uç noktaları tanımlamak için hafif bir şablon

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.

Uç nokta davranış notu şablonu

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 ile OpenAPI taslağı oluşturma (işe yarayan prompt)

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.

Çalışan API ile karşılaştırmadan önce spec’i doğrulayın

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:

• Gerekli vs opsiyonel: gerekli alanları doğru işaretleyin ve “her şey opsiyonel”den kaçının.
• Tipler ve formatlar: UUID, email, date-time, min/max değerler açık olsun.
• Örnekler: her uç nokta için en az bir gerçekçi istek ve yanıt örneği ekleyin; örnekler şemalarla uyumlu olsun.
• Durum kodları: davranış notlarıyla hizalayın (create genelde 201 döner). 400 vs 422 seçimini tutarlı yapın.
• Auth: her uç nokta için neyin gerekli olduğu ve rollerin erişimi etkileyip etkilemediği açık olsun.

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 ile çalışan API uygulamasını karşılaştırma

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:

• Davranış doğru ama belgelenmemişse: spec’i düzeltin.
• Spec anlaşılmış sözleşmeyse: kodu düzeltin.
• Hiçbiri doğru değilse: önce amaçlanan davranışı değiştirin, sonra her ikisini güncelleyin.

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.

Sözleşmeden istemci ve sunucu doğrulama örnekleri üretin

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.

Sunucu tarafı doğrulama (geçersiz istekleri reddetmek)

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"}}}
}

İstemci tarafı doğrulama (kırılmaları erken yakalamak)

İ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:

• Sabit değerler yerine varlık ve tipe bakın.
• Opsiyonel bir alan kritik değilse onu assert etmeyin.
• Hatalarda durum ve hata kodunu kontrol edin, tam mesajları değil.
• Ek alanlara izin verin, spec açıkça yasaklamadıkça.

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.

Örnek senaryo: Basit bir Tasks API uçtan uca

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:

• Başarı: { "title": "Buy milk" } gönderin ve yeni görev nesnesiyle 201 dönün; nesnede id, title ve done:false olsun.
• Hata 1: {} gönderildiğinde 400 dönsün { "error": "title is required" } gibi.
• Hata 2: { "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şmeyi sahte yapan yaygın hatalar

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:

• İsimler ve tipler uç noktalar arasında savrulur (taskId bir route’da, id başka yerde; ya da priority bir yanıtta string, diğerinde sayı olur).
• Örnekler şemalarla çelişir (enum değerleri uymuyor, date-time örnekleri ISO 8601 değil).
• Karar vermekten kaçınmak için tipler genişletilir (her şey string olur, her şey opsiyonel olur).
• Spec pazarlama kopyası gibi okunur (“hızlı”, “güvenli”) test edilebilir bir sözleşme yerine.

İ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.

Paylaşmadan veya yayımlamadan önce hızlı kontroller

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:

• Gerekli alanlar, formatlar (email, uuid, date-time) ve enumlar açık.
• Durum kodları benzer uç noktalar arasında kasıtlı ve tutarlı.
• Hata yanıtları hem şema hem örnek içerir, sadece durum kodu değil.
• Her uç nokta için 2-3 gerçek çağrı (test, curl, Postman veya log) tekrar çalıştırılıp yükler spec ile karşılaştırılmış.
• Spec’tan başlıksız bir küçük istemci çağrısı yazabiliyorsanız, başlıklar, alan adları veya null olabilirlik için tahminde bulunmanız gerekmiyordur.

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.

Sonraki adımlar: alışkanlık haline getirin (ve değişiklikleri güvenli tutun)

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:

• Yeni bir uç nokta eklerken davranış notlarını yazın
• Spec’i doğrulayın ve sözleşme testlerini merge etmeden çalıştırın
• Yayından önce çalışan API ile spec’i karşılaştırın
• Riskli değişikliklerden önce anlık görüntü alın; diff kafa karıştırıcıysa rollback yapın

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.