F1 · OpenAPI Spec Nedir? Sözleşme: Bir OpenAPI spec'i (`openapi.yaml`/`.json`), bir binanın **mimari çizimidir** — bina (kod) zaten var ve çalışıyor, ama bir elektrikçinin (başka
Bir OpenAPI spec'i (`openapi.yaml`/`.json`), bir binanın **mimari çizimidir** — bina (kod) zaten var ve çalışıyor, ama bir elektrikçinin (başka bir ekibin, bir test aracının) binayı anlamak için içeri girip her odayı elle dolaşmasına gerek yoktur; çizime bakması yeterlidir. GRUP A'da "sözleşme" kavramını görmüştün (A1) — OpenAPI spec, o soyut sözleşmeyi **makine-okunur, standart bir formata** döker: hangi yol (`/api/v1/bugs`) hangi metodu (GET/POST) kabul eder, hangi alanlar zorunludur, response nasıl görünür — hepsi TEK bir dosyada, İngilizce açıklama okumaya gerek kalmadan. Peki kod zaten varken (Java'da bir `Controller` sınıfı, TypeScript'te bir DTO) neden ayrı bir spec dosyasına ihtiyaç var? Çünkü kod SADECE o dili bilen bir geliştiricinin okuyabileceği bir formattadır; spec ise Postman, Swagger UI, kod üretici araçlar, sözleşme testleri gibi ONLARCA farklı aracın AYNI ANDA okuyabileceği ORTAK bir dildir. Java'da bunun en yakın karşılığı bir `interface` + JavaDoc birleşimidir: `interface` metodun İMZASINI (ne alır, ne döner) garanti eder, JavaDoc bunu İNSAN tarafından okunur açıklar; OpenAPI spec ikisini birden, hem makine hem insan için, TEK dosyada yapar. QA açısından bu spec, kod okumadan bir API'nin sözleşmesini öğrenmenin en hızlı yoludur — ve GRUP F boyunca göreceğin gibi, bu sözleşme ile GERÇEĞİN AYRIŞTIĞI an, tam olarak bir "contract defect"in doğduğu andır.
/api/v1/bugs — Minimum Bir Spec
🎬 Kod Var, Ama Kimse Onu Okumak Zorunda Değil
Postman / Swagger UI / Testler
Tester kod okumadan öğrenir
Bir geliştirici `/api/v1/bugs` için Controller kodunu yazar — sözleşme kodun İÇİNDE gömülüdür.
Bu sözleşme `openapi.yaml`'e DÖKÜLÜR — artık kod okumadan da okunabilir bir formattadır.
Postman, Swagger UI, sözleşme testleri — ONLARCA araç bu TEK dosyayı AYNI ANDA okuyabilir.
Ders — Tester, Java/TypeScript bilmese bile spec'i okuyarak API'nin ne kabul ettiğini, ne döndürdüğünü öğrenir.
Bir Sözleşmenin Kaynak Kod → Spec Yolculuğu
Controller/DTO sınıfları sözleşmeyi kodun içinde taşır — ama sadece geliştirici okuyabilir.
Spec üretilir/yazılır…
openapi.yaml, aynı sözleşmeyi standart, makine-okunur bir formata döker (F2'de otomatik üretimi göreceksin).
Swagger UI, Postman, test araçları kod OKUMADAN spec'ten API'yi anlar.