OpenAPI, bir HTTP API'sini sıradan bir YAML ya da JSON dosyasında tarif etmeye yarayan bir biçimdir. Dosyada API'nin hangi yolları sunduğu, her yolun hangi metotları kabul ettiği, istekte hangi alanların gittiği ve yanıtın ne döndürdüğü yazar. Dosyayı hem insan hem program okuyabildiği için dokümantasyon, istemci kütüphaneleri ve testlerde kullanılan sahte sunucular aynı kaynaktan üretilebilir.

Resmî adı OpenAPI Specification, kısaca OAS. Linux Foundation çatısı altındaki açık yönetişimli bir proje olan OpenAPI Initiative tarafından sürdürülüyor.

Aşağıda: belgenin nasıl kurulduğu, OpenAPI ile Swagger'ın farkı, 3.1 ve 3.2'de nelerin değiştiği ve bu biçimin en temel vaadinin — hiç eskimeyen dokümantasyon — kendi kendine neden gerçekleşmediği.

Bir OpenAPI belgesi neye benzer

Çalışan bir dosya çoğu kişinin sandığından kısadır:

openapi: 3.1.0

info:
  title: Bağlantılar
  version: "1.0"

paths:
  /links:
    post:
      summary: Kısa bağlantı oluştur
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
      responses:
        '201':
          description: Bağlantı oluşturuldu

Üst düzeyde zorunlu alan yalnızca iki tane: openapi ve info. Bunların yanı sıra belge paths, components ve webhooks alanlarından en az birini içermek zorunda. OAS 3.1.1 spesifikasyonu bunu böyle tanımlıyor.

Daha bu ilk satırlarda bir tuzak var: openapi ile info.version aynı şey değil. Birincisi biçimin kendi sürümü; araçlar belgeyi nasıl yorumlayacaklarına ona bakarak karar veriyor. İkincisi ise sizin API'nizin sürümü. Spesifikasyon bunu açıkça söylüyor ama sezgi tersini fısıldadığı için ortalıkta openapi: 1.0 diye başlayan dosyalar dolaşıyor.

Büyük spesifikasyonlar genellikle $ref ile birden çok dosyaya bölünür: kök belge ./paths/links.yaml dosyasını, o da ./schemas/link.yaml dosyasını gösterir. Pratik bir çözüm, ama sonunda döneceğim bir soruna yol açıyor.

OpenAPI ile Swagger aynı şey değil

Konunun en yaygın karışıklığı bu.

Nedir Kim sürdürüyor
OpenAPI standardın kendisi, yani biçim OpenAPI Initiative, Linux Foundation
Swagger bu biçimi okuyan araç ailesi SmartBear

Karmaşanın nedeni tarihte. Başlangıçta Swagger hem spesifikasyonu hem araçları anlatıyordu. Sonra spesifikasyon OpenAPI Initiative'e devredilip OpenAPI Specification adını aldı; Swagger adı ise araçlarda kaldı — Swagger UI, Swagger Editor ve diğerleri.

Pratikte "biz Swagger kullanıyoruz" neredeyse her zaman "elimizde bir OpenAPI dosyası var, onu Swagger UI ile gösteriyoruz" demektir. İkisi birbirine bağlı değil: aynı dosya Redoc'ta, Scalar'da ya da bir istemci üretecinde de aynı şekilde açılır.

Sürümler: 3.0, 3.1 ve 3.2

Dallar arasındaki farklar kozmetik değil.

3.0 hâlâ en yaygın kullanılanı. Zayıf noktası veri şemaları: JSON Schema'ya benziyorlar ama onunla tam uyumlu değiller, bu da araçlar arası birlikte çalışabilirliği sürekli bozuyor.

3.1 bu boşluğu kapattı. Schema nesnesi JSON Schema Draft 2020-12'nin üst kümesi hâline geldi; böylece zaten JSON Schema ile tuttuğunuz şemalar yeniden yazılmak yerine olduğu gibi kullanılabiliyor. Yürürlükteki düzeltme olan 3.1.1, 24 Ekim 2024'te yayımlandı.

3.2 Eylül 2025'te geldi. OpenAPI Initiative'in duyurusuna göre öne çıkanlar:

  • parametreleri URL'ye sığmayan etkisiz okumalar için query HTTP metodu;
  • standart dışı metotlar için additionalOperations;
  • akış ortam türleri: Server-Sent Events, JSON Lines, JSON dizileri;
  • summary, parent ve kind ile hiyerarşik etiketler;
  • girişi zahmetli cihazlar için OAuth 2.0 cihaz akışı.

Sürümü en büyük numaraya göre değil, araçlarınızın gerçekten desteklediğine göre seçmek gerekir. Ekosistemin 3.1 desteği sağlam; 3.2 daha yeni ve araç zincirinin bir kısmı hâlâ yetişmeye çalışıyor. Bizim kendi spesifikasyonumuz 3.1.0 olarak tanımlı.

Pratikte ne kazandırıyor

Tek dosya aynı anda birkaç işi birden görüyor:

  • etkileşimli dokümantasyon — Swagger UI ya da Redoc sayfayı doğrudan dosyadan kuruyor, istek deneme formu dahil;
  • istemci kütüphaneleri — üreteçler dilinize uygun bir SDK çıkarıyor, elle sarmalayıcı yazmaya gerek kalmıyor;
  • sahte sunucular — arka uç hazır olmadan açıklamaya bakarak bir mock sunucu ayağa kalkıyor, ön uç beklemiyor;
  • sözleşme testleri — testler gerçek yanıtları şemalarla karşılaştırıyor ve bir yanıtın açıklamasıyla örtüşmeyi bıraktığı anı yakalıyor.

OpenAPI lehine en güçlü argüman bu listeden çıkıyor: dokümantasyon, birinin güncellemeyi unuttuğu ayrı bir metin olmaktan çıkıyor.

Argüman doğru. Yalnızca kendiliğinden işlemiyor.

Spesifikasyonu koda bağlayan hiçbir şey yok

"OpenAPI nedir" yazılarının neredeyse hiç değinmediği, canlıda ise ısıran kısım bu.

Spesifikasyon dosyası yalnızca bir dosyadır. Yönlendirici onun varlığından habersizdir. Denetleyici de öyle. Bir uç noktayı silebilir, yenisini ekleyebilir, zorunlu bir alanı isteğe bağlı yapabilirsiniz — tek bir test bile düşmez. Dokümantasyon kendi kendine eşitlenmez; tam olarak biri onu düzenlemeyi hatırladığı sürece doğru kalır.

Ayrışma iki yönde birden olur ve her yönün zararı başkadır:

  • yazılmış ama çalışmıyor. Geliştirici dokümantasyonu okuyup isteği gönderiyor ve 404 alıyor. Dokümantasyonun geri kalanına duyulan güven o anda çöküyor: burada yanlışsa, başka nerede yanlış?
  • çalışıyor ama yazılmamış. Onu arayan biri için o yetenek hiç yok demektir. Kimse bulmaz, kimse parasını ödemez.

Asıl tehlikeli olan ikincisi, çünkü kimse şikâyet etmiyor. Edecek kimse de yok: kullanıcı o uç noktanın var olduğunu bilmiyor.

Bizim başımıza tam olarak bu geldi. Lix.li API'sinde dönüşümlerle ilgili üç uç nokta çalışıyordu — bir olay listesi ile tekli ve toplu postback alımı — ve hiçbiri spesifikasyonda yer almıyordu. Kod çalışıyordu, testler geçiyordu, bu sırada API tanıtım sayfasında kodda hiç bulunmayan bambaşka iki yol sergileniyordu. Bu bir hata bildirimiyle değil, baştan sona yapılan bir karşılaştırmada ortaya çıktı.

Ayrışmayı otomatik yakalamak

Bu iş disiplinle değil testle çözülüyor. Fikir yalın: spesifikasyondaki yolların listesini al, yönlendiricideki kuralların listesini al ve iki kümeyi her iki yönde karşılaştır.

openapi.yaml'daki yollar   →   böyle bir rota var mı?   →   yoksa dokümantasyon yalan söylüyor
yönlendiricideki rotalar   →   yol yazılmış mı?         →   yazılmamışsa özellik görünmez

"Yazılan çalışıyor" tarafını gerçek bir istekle sınamak en rahatı: uç noktayı kimlik bilgisi olmadan çağırıp yanıtın 404 değil 401 olduğunu doğrulamak. Bu ayrım önemli. 401, rotanın bulunduğunu ve anahtar istediğini; 404 ise öyle bir yolun olmadığını gösterir. Bu sırada hiçbir şey yazılmaz, çünkü kimlik doğrulama denetleyiciden önce çalışır.

Ters yöndeki denetim rota yapılandırmasını okur. Ayrıca istisnaları açıkça saymaya zorlar — herkese açık bir sözleşmede işi olmayan dahili uç noktaları. Bu istisna listesi kendi başına değerlidir: neyi kendi genel API'niz saydığınıza bir kez, bilinçli olarak karar vermenizi sağlar.

Dönüşümler olayından sonra bu testi yazdık. Kendini hemen kanıtladı: dönüşümleri spesifikasyondan yeniden çıkarın, test düşüyor ve eksik iki yolu tek tek adlandırıyor.

Geç fark edilen iki tuzak

$ref ve göreli yollar. Spesifikasyon birden çok dosyaya bölündüğünde içindeki başvurular, dosyanın sunulduğu adrese göre çözülür. /openapi altında duran bir kök belge, ./paths/links.yaml dosyasını /paths/links.yaml adresinde arar ve bulamaz. Tarayıcıda her şey yolunda görünür, çünkü Swagger UI dosyayı gerçek yerinden yükler; aynı belgeye yöneltilen bir istemci üreteci ise takılır. Ya spesifikasyonu yalnızca kendi dizininden sunun ya da dış $ref içermeyen tek bir dosyada toplayın.

Swagger UI tarayıcı robotu için boştur. Swagger UI sayfası birkaç satır işaretleme ile içeriği tarayıcıda çizen bir betikten ibarettir. Sunulan HTML'de tek bir uç nokta yolu geçmez. Okuyan için sayfa normaldir, dizine ekleme açısından bomboştur. Buna bir de robots.txt içindeki yaygın hata eklenir: JSON uç noktalarını gizlemek için yazılan Disallow: /api/ kuralı, aynı önek altında yaşayan insanlar için hazırlanmış dokümantasyonu da birlikte gizler. Kapatılması gereken, sürüm numarasını içeren tam yoldur — örneğin /api/1.0/ — bölümün tamamı değil.

Nereden başlamalı

API zaten varsa ve açıklaması yoksa sıra aşağı yukarı şöyle:

  1. Bir uç noktayı elle tarif edin. Yapıyı kavramak için bu yeter.
  2. Araçlarınızın rahatça desteklediği sürümü seçin; varsayılan olarak 3.1.
  3. Dosya bir ekrana sığmamaya başladığında $ref ile bölün ve hangi adresten sunulacağını hemen kararlaştırın.
  4. Spesifikasyonu yönlendiriciyle iki yönde karşılaştıran bir test kurun. Bu adıma kadar dokümantasyonun güncelliğine dair her söz bir vaattir, bir özellik değil.

Gerçek bir API'de bunun nasıl göründüğünü Lix.li API dokümantasyonunda görebilirsiniz: bağlantılar, gruplar, A/B testleri ve dönüşümler orada. Bu API'nin etrafında kurulan hizmet için bağlantı kısaltma API sayfası, komşu konular içinse webhook nedir ve 301, 302, 307, 308 yönlendirmeleri ile istek yöntemi çözümlemesi var.