TL;DR
OpenAPI 3.1 tam JSON Şema uyumluluğu, webhook'lar ve ayırıcı iyileştirmeleri ekledi. OpenAPI 3.2 QUERY yöntem desteği, geliştirilmiş örnekler ve daha iyi güvenlik tanımları ekledi. Modern PetstoreAPI, tüm yeni özelliklerini üretime hazır örneklerle göstermek için OpenAPI 3.2'yi kullanmaktadır.
Giriş
Bir OpenAPI belirtimi yazıyorsunuz. OpenAPI 3.0, 3.1 ve 3.2 referansları görüyorsunuz. Fark ne? Yükseltmeli misiniz? Araçlarınız yeni sürümü destekleyecek mi?
OpenAPI 3.0'dan 3.2'ye önemli ölçüde gelişti. Her sürüm, API belirtimlerini daha güçlü ve doğru hale getiren özellikler ekler. Ancak tüm araçlar en son sürümleri desteklemiyor, bu da bir uyumluluk sorunu yaratıyor.
Eski Swagger Petstore, OpenAPI 2.0'ı (Swagger belirtimi) kullanır. Modern PetstoreAPI, her yeni özelliği üretime hazır örneklerle sergilemek için OpenAPI 3.2'yi kullanır.
düğme
Bu kılavuzda, her OpenAPI sürümünde nelerin değiştiğini, doğru sürümü nasıl seçeceğinizi ve Modern PetstoreAPI'nin OpenAPI 3.2 özelliklerini nasıl gösterdiğini öğreneceksiniz.
OpenAPI 3.0 Temeli
OpenAPI 3.0 (Temmuz 2017'de yayınlandı) Swagger 2.0'dan büyük bir yükseltmeydi.
Temel Özellikler
1. Çoklu sunucular
servers:
- url: https://api.petstoreapi.com/v1
description: Production
- url: https://staging.petstoreapi.com/v1
description: Staging
Swagger 2.0 yalnızca tek bir ana bilgisayarı destekliyordu.
2. İstek gövdesi nesnesi
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
Swagger 2.0'ın `body` parametresinden daha net.
3. Yeniden kullanılabilirlik için bileşenler
components:
schemas:
Pet:
type: object
responses:
NotFound:
description: Resource not found
parameters:
PetId:
name: petId
in: path
Swagger 2.0'ın `definitions`'ından daha iyi organizasyon.
4. Geri Çağrımlar (Callbacks)
Asenkron geri çağrımları (webhook'lar) tanımlayın:
callbacks:
orderUpdate:
'{$request.body#/callbackUrl}':
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderUpdate'
5. Bağlantılar
İşlemler arasındaki ilişkileri tanımlayın:
links:
GetPetByPetId:
operationId: getPetById
parameters:
petId: '$response.body#/id'
Sınırlamalar
1. JSON Şema uyumsuzluğu
OpenAPI 3.0, tam JSON Şema değil, JSON Şema Taslağı 5'in bir alt kümesini kullanıyordu. Bu, doğrulama sorunlarına neden oldu.
2. Webhook nesnesi yok
Webhook'lar, kafa karıştırıcı olan geri çağrımlar olarak tanımlanıyordu.
3. Sınırlı ayırıcı (discriminator)
Polimorfizm desteği temel düzeydeydi.
4. Null tipi yok
`type: null` değerini doğrudan belirtemiyordunuz.
OpenAPI 3.1 Ana Değişiklikler
OpenAPI 3.1 (Şubat 2021'de yayınlandı) JSON Şema uyumuna odaklandı.
1. Tam JSON Şema 2020-12 Uyumluluğu
En büyük değişiklik: OpenAPI 3.1 şemaları geçerli JSON Şema 2020-12'dir.
Önce (OpenAPI 3.0):
type: string
nullable: true # OpenAPI'ye özgü
Sonra (OpenAPI 3.1):
type: [string, "null"] # Standart JSON Şema
Faydaları:
- Herhangi bir JSON Şema doğrulayıcı kullanın
- OpenAPI ve diğer araçlar arasında şemaları paylaşın
- Tam JSON Şema özelliklerine erişim
2. Webhook Nesnesi
Önce (OpenAPI 3.0):
# Webhook'lar geri çağrımlar olarak tanımlandı (kafa karıştırıcı)
paths:
/subscribe:
post:
callbacks:
orderUpdate:
# webhook tanımı
Sonra (OpenAPI 3.1):
webhooks:
orderUpdate:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderUpdate'
API uç noktaları ve webhook'lar arasında daha net ayrım.
3. Geliştirilmiş Ayırıcı (Discriminator)
Daha iyi polimorfizm desteği:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
discriminator:
propertyName: petType
mapping:
cat: '#/components/schemas/Cat'
dog: '#/components/schemas/Dog'
4. Bilgi Nesnesi Lisans Tanımlayıcısı
info:
license:
name: MIT
identifier: MIT # SPDX tanımlayıcı
5. PathItem $ref
Tüm yol öğelerine referans verin:
paths:
/pets:
$ref: '#/components/pathItems/PetsCollection'
Kritik Değişiklikler
1. `nullable` kaldırıldı
Bunun yerine `type: [string, "null"]` kullanın.
2. `exclusiveMinimum` / `exclusiveMaximum` değişti
Artık boole, sayısal değil.
3. `example` ve `examples`
Daha sıkı doğrulama.
OpenAPI 3.2 En Son Özellikler
OpenAPI 3.2 (yayın tarihi belirlenecek, taslak mevcut) modern API kalıpları ekler.
1. QUERY Yöntemi Desteği
Karmaşık aramalar için HTTP QUERY yöntemi:
paths:
/pets/search:
query: # Yeni yöntem
requestBody:
content:
application/json:
schema:
type: object
properties:
filters:
type: object
sort:
type: array
responses:
'200':
description: Search results
Modern PetstoreAPI, karmaşık evcil hayvan aramaları için QUERY'yi kullanır.
2. Geliştirilmiş Örnekler
Meta veri içeren çoklu örnekler:
examples:
availableCat:
summary: Available cat
description: A cat available for adoption
value:
id: "019b4132-70aa-764f-b315-e2803d882a24"
name: "Fluffy"
species: "CAT"
status: "AVAILABLE"
adoptedDog:
summary: Adopted dog
value:
id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
name: "Buddy"
species: "DOG"
status: "ADOPTED"
3. Geliştirilmiş Güvenlik Tanımları
Daha iyi OAuth 2.0 desteği:
components:
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://petstoreapi.com/oauth/authorize
tokenUrl: https://petstoreapi.com/oauth/token
refreshUrl: https://petstoreapi.com/oauth/refresh
scopes:
pets:read: Read pets
pets:write: Create and update pets
orders:read: Read orders
4. Geliştirilmiş Ayırıcı Haritalaması
Daha esnek polimorfizm:
discriminator:
propertyName: type
mapping:
cat: Cat
dog: Dog
bird: '#/components/schemas/Bird' # Yerel ve $ref'i karıştırabilir
5. Daha İyi Kullanımdan Kaldırma Desteği
Belirli alanları kullanımdan kaldırın:
properties:
oldField:
type: string
deprecated: true
description: Use newField instead
newField:
type: string
Modern PetstoreAPI OpenAPI 3.2'yi Nasıl Kullanır
Modern PetstoreAPI, her OpenAPI 3.2 özelliğini sergiler.
1. Tam Belirtim
Tam OpenAPI 3.2 belirtimi şu adreste mevcuttur:
https://petstoreapi.com/openapi.json
2. Karmaşık Aramalar İçin QUERY Yöntemi
/pets/search:
query:
summary: Search pets with complex criteria
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetSearchQuery'
3. Webhook'lar
webhooks:
petStatusChanged:
post:
summary: Pet status changed
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetStatusWebhook'
4. Polimorfik Şemalar
Pet:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Bird'
discriminator:
propertyName: species
5. Kapsamlı Örnekler
Her uç nokta, farklı senaryoları gösteren birden fazla örnek içerir.
6. RFC 9457 Hata Yanıtları
responses:
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
Tüm özellikler için tam OpenAPI belirtimine bakın.
Geçiş Kılavuzu
3.0'dan 3.1'e
1. `nullable` değerini değiştirin:
# Önce
type: string
nullable: true
# Sonra
type: [string, "null"]
2. `exclusiveMinimum` / `exclusiveMaximum` değerini güncelleyin:
# Önce
minimum: 0
exclusiveMinimum: true
# Sonra
minimum: 0
exclusiveMinimum: 0
3. Webhook'ları taşıyın:
# Önce
paths:
/subscribe:
callbacks:
# webhook
# Sonra
webhooks:
# webhook
3.1'den 3.2'ye
1. Uygun yerlere QUERY yöntemleri ekleyin:
/pets/search:
query: # 3.2'deki yenilik
# karmaşık arama
2. Örnekleri geliştirin:
examples:
example1:
summary: Description
value: {...}
3. Güvenlik tanımlarını güncelleyin:
OAuth akışlarına `refreshUrl` ekleyin.
Apidog ile OpenAPI Belirtimlerini Test Etme
Apidog tüm OpenAPI sürümlerini destekler.
OpenAPI Belirtimini İçe Aktarma
1. Apidog'u açın
2. "İçe Aktar"a tıklayın
3. "OpenAPI 3.x"i seçin
4. URL'yi yapıştırın veya dosyayı yükleyin
5. Apidog doğrular ve içe aktarır
Belirtimi Doğrulama
Apidog şunları kontrol eder:
- Şema geçerliliği
- Referans bütünlüğü
- Örnek doğruluğu
- Güvenlik tanımı eksiksizliği
API Uygulamasını Test Etme
Belirtimden test durumları oluşturun:
- İstek doğrulama
- Yanıt doğrulama
- Durum kodu kontrolleri
- Şema uyumluluğu
Sürüm Karşılaştırması
Birden çok sürümü içe aktarın ve karşılaştırın:
- Kritik değişiklikler
- Yeni uç noktalar
- Şema değişiklikleri
- Kullanımdan kaldırılan alanlar
Sonuç
OpenAPI önemli ölçüde gelişti:
OpenAPI 3.0: Sunucular, istek gövdeleri, geri çağrımlar ile temel
OpenAPI 3.1: JSON Şema uyumluluğu, webhook nesnesi, daha iyi polimorfizm
OpenAPI 3.2: QUERY yöntemi, geliştirilmiş örnekler, geliştirilmiş güvenlik
Modern PetstoreAPI, tüm özelliklerini üretime hazır örneklerle göstermek için OpenAPI 3.2'yi kullanır. Modern API tasarımı için referans uygulamadır.
Herhangi bir OpenAPI sürümüyle çalışmak, belirtimleri doğrulamak ve uygulamaları test etmek için Apidog'u kullanın.
Sıkça Sorulan Sorular
OpenAPI 3.1 veya 3.2'ye yükseltmeli miyim?
Araçlarınız destekliyorsa, evet. OpenAPI 3.1'in JSON Şema uyumluluğu değerlidir. OpenAPI 3.2, QUERY yöntemi gibi modern kalıplar ekler.
OpenAPI 3.0 belirtimim 3.1 araçlarıyla çalışacak mı?
Çoğunlukla, ancak `nullable` ve `exclusiveMinimum` / `exclusiveMaximum` güncellemeler gerektirir.
Kod oluşturucular OpenAPI 3.2'yi destekliyor mu?
Destek artıyor. Oluşturucunuzun belgelerini kontrol edin. Birçoğu 3.1'i destekler, daha azı ise 3.2'yi destekler.
OpenAPI 3.2 özelliklerini 3.1'de kullanabilir miyim?
Hayır. Özelliklerinize uyan sürümü kullanın. QUERY yöntemine ihtiyacınız varsa, 3.2'yi kullanın.
OpenAPI belirtimimi nasıl doğrularım?
Belirtiminizi içe aktarmak ve doğrulamak için Apidog'u kullanın. Şema geçerliliğini ve referans bütünlüğünü kontrol eder.
Tam bir OpenAPI 3.2 örneğini nerede görebilirim?
Modern PetstoreAPI, eksiksiz, üretime hazır bir OpenAPI 3.2 belirtimi sunar.
Webhook'lar ve geri çağrımlar arasındaki fark nedir?
Webhook'lar, sunucudan istemciye HTTP istekleridir. Geri çağrımlar, OpenAPI 3.0'da işlemlerin bir parçası olarak tanımlanır. OpenAPI 3.1+ özel bir `webhooks` nesnesine sahiptir.
OpenAPI belirtimleri için JSON mı yoksa YAML mı kullanmalıyım?
Her ikisi de çalışır. YAML insanlar için daha okunabilirdir. JSON araçlar için daha kolaydır. Modern PetstoreAPI her iki formatı da sağlar.