OpenAPI (Swagger) Spesifikasyonu ile API Dokümantasyonu ve Code Generation

OpenAPI (Swagger) Spesifikasyonu ile API Dokümantasyonu ve Code Generation

OpenAPI (eski adıyla Swagger), REST API'lerini tanımlamak, belgelemek ve tüketmek için endüstri standardı haline gelmiş bir spesifikasyondur. Bir API'nin yeteneklerini, kaynak koduna erişmeden hem insanların hem de makinelerin anlayabileceği bir formatta sunar. 2026 itibarıyla OpenAPI ekosistemi, hem spesifikasyon hem de araç desteği açısından önemli bir olgunluğa ulaşmıştır.

1. OpenAPI 3.2: Yeni Nesil Spesifikasyon

OpenAPI 3.2.0, 2025'in sonlarında yayınlanmış ve 3.1 ile tam geriye dönük uyumluluğu korumuştur. Geçiş için tek gereken, dokümandaki openapi sürüm numarasını 3.2.0 olarak güncellemektir .

Öne Çıkan Yenilikler:

Streaming Desteği: text/event-stream, application/jsonl gibi akış medya tipleri artık birinci sınıf vatandaştır. itemSchema alanı ile akıştaki her bir öğenin şeması tanımlanabilir; böylece kod üreticileri, ham metin yerine tipli nesneler döndüren iterator'lar üretebilir .
Hiyerarşik Etiketler (Tags): Etiketler artık summary, parent ve kind alanlarıyla hiyerarşik olarak organize edilebilir. Bu, büyük API yüzeylerinde gezinmeyi kolaylaştırır ve SDK'ların mantıksal modüller halinde üretilmesini sağlar .
Ek HTTP Metotları: QUERY metodu resmiyet kazanmış; additionalOperations alanı ile PROPFIND, PURGE gibi standart dışı metotlar da tanımlanabilir hale gelmiştir .
$self Alanı: Dokümanın kendi URI'sini beyan etmesini sağlayarak çoklu dosya senaryolarında referans çözümlemesini netleştirir .

Ekosistem Durumu: Swagger UI, Swagger Editor ve Swagger Client gibi araçlar 3.2.0 desteğini duyurmuştur . Ancak bazı popüler doğrulayıcılar (ör. @apidevtools/swagger-parser) hâlâ 3.1'de kaldığı için, 3.2 dokümanları her araçta sorunsuz doğrulanamayabilir; bu geçiş döneminde normaldir .

2. .NET'te OpenAPI Dokümantasyonu

.NET 9 ve sonrası, ASP.NET Core'da yerleşik OpenAPI doküman üretimi sunar. Microsoft.AspNetCore.OpenApi paketi ile AddOpenApi() ve MapOpenApi() çağrıları yeterlidir.

csharp

// Program.cs
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi(); // /openapi/v1.json endpoint'i

Önemli Değişiklik (.NET 10): WithOpenApi() uzantı metodu kullanımdan kaldırılmıştır (ASPDEPR002). Bunun yerine, doküman üzerinde değişiklik yapmak için AddOpenApiOperationTransformer kullanılmalıdır. Swashbuckle kullanıyorsanız IOperationFilter, NSwag kullanıyorsanız IOperationProcessor tercih edilmelidir .

Çoklu Doküman Üretimi: Aynı uygulamadan farklı izleyiciler (public/internal) veya sürümler için birden fazla OpenAPI dokümanı üretilebilir:

csharp

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

Her doküman, ShouldInclude delegesi ile hangi endpoint'lerin dahil edileceğini özelleştirebilir .

Derleme Zamanında Üretim: Microsoft.Extensions.ApiDescription.Server paketi ile OpenAPI dokümanı derleme sırasında oluşturulup çıktı klasörüne yazılabilir; bu, dokümanın kaynak kontrolüne eklenmesi veya statik sunulması için idealdir .

3. Code Generation: İstemci Kodu Üretimi

OpenAPI spesifikasyonunun en güçlü yanlarından biri, güçlü tipli istemci kodu üretimidir.

Microsoft.dotnet-openapi (Global Tool):

Bu araç, bir OpenAPI dokümanından C# veya TypeScript istemci kodu üretir. Projeye <OpenApiReference /> ekleyerek çalışır.

bash

# Kurulum
dotnet tool install -g Microsoft.dotnet-openapi

# Dosyadan referans ekleme (varsayılan: NSwagCSharp)
dotnet openapi add file ./openapi.json --code-generator NSwagCSharp

# URL'den referans ekleme
dotnet openapi add url https://contoso.com/openapi.json

# Referansı yenileme
dotnet openapi refresh https://contoso.com/openapi.json

Araç, --code-generator seçeneğiyle NSwagCSharp veya NSwagTypeScript üreticilerini destekler .

OpenAPI Generator (Topluluk):

Swagger Codegen'den fork'lanan OpenAPI Generator, 50'den fazla dilde istemci ve sunucu iskeleti üretebilir. C# ASP.NET Core için sunucu stub'ları da mevcuttur .

Kaynak Üreticileri (Source Generators):

TeknixIT.OpenApiGenerator.Server gibi NuGet paketleri, OpenAPI şemalarından derleme zamanında C# sözleşmeleri ve controller'lar üretir. .NET 8, 9 ve 10+ desteklenir .

4. Ne Zaman Hangi Yaklaşım?

Senaryo	Öneri
Kendi ASP.NET Core API'niz için dokümantasyon	Yerleşik `AddOpenApi()` + `MapOpenApi()`
Harici bir API için C# istemci kodu	`Microsoft.dotnet-openapi` (NSwagCSharp)
Çoklu dilde SDK üretimi	OpenAPI Generator
Sunucu iskeleti (contract-first)	OpenAPI Generator (ASP.NET Core stub) veya kaynak üreticileri
Dokümanı CI/CD'de statik olarak üretmek	`Microsoft.Extensions.ApiDescription.Server`

5. En İyi Pratikler

Pratik	Açıklama
OpenAPI 3.2'ye geçin	Sadece sürüm numarasını değiştirerek geriye dönük uyumlu geçiş yapın .
`WithOpenApi()` kullanmayın	.NET 10'da kullanımdan kaldırıldı; `AddOpenApiOperationTransformer` kullanın .
Dokümanı sürümleyin	API sürümleriyle OpenAPI doküman sürümlerini eşleştirin.
Üretilen kodu gözden geçirin	Otomatik üretilen istemci kodunu, API sözleşmesiyle uyum için test edin.
Üretimde dokümanı kısıtlayın	OpenAPI endpoint'ini yalnızca geliştirme/staging ortamlarında açık tutun .

Sonuç

OpenAPI, API'lerin hem dokümantasyonu hem de kod üretimi için vazgeçilmez bir standarttır. 3.2 sürümü, streaming ve hiyerarşik etiketler gibi modern ihtiyaçlara cevap verirken geriye dönük uyumluluğu korur. .NET ekosisteminde yerleşik AddOpenApi() desteği ve Microsoft.dotnet-openapi aracı, dokümantasyon ve istemci kodu üretimini standartlaştırmıştır. Unutmayın: İyi bir OpenAPI dokümanı, API'nizin hem aynası hem de sözleşmesidir; onu güncel tutmak, istemcilerinizle olan güveni korur.

İlgili yazılar