API Tasarımı & Geliştirme Araçları 37 okunma

OpenAPI ve Kod Üretimi

OpenAPI (eski adıyla Swagger), REST API'lerini tanımlamak için kullanılan dil-agnostik bir spesifikasyondur. Bu yazıda, OpenAPI spesifikasyonunun temelleri, .NET'te dokümantasyon oluşturma yöntemleri, Swagger UI ile etkileşimli test, NSwag ve Swagger Codegen ile kod üretimi (istemci/SDK, sunucu iskeleti) ve en iyi pratikler ele alınır.

OpenAPI ve Kod Üretimi

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. 2015 yılında Swagger projesi OpenAPI Initiative'e bağışlanmıştır; günümüzde "OpenAPI" spesifikasyonu, "Swagger" ise bu spesifikasyonla çalışan SmartBear ürün ailesini ifade eder. OpenAPI, hem insanların hem de makinelerin bir API'nin yeteneklerini kaynak koduna erişmeden anlamasını sağlayarak, servisler arası bağlantı kurma iş yükünü ve dokümantasyon süresini azaltmayı hedefler.

1. OpenAPI Spesifikasyonu ve Versiyonları

OpenAPI spesifikasyonu, API'nizi bir openapi.json veya openapi.yaml dosyası ile tanımlar. 2026 itibarıyla en güncel sürüm OpenAPI 3.1'dir.

OpenAPI 3.1'in Getirdiği Yenilikler:

  • Tam JSON Schema 2020-12 Uyumluluğu: Veri modelleri artık JSON Schema ile tamamen uyumludur. nullable özelliği kaldırılmış, bunun yerine type dizisi içinde null kullanılmaktadır.

  • Webhook Desteği: API'nizin tetiklediği webhook'ları tanımlayabilirsiniz.

  • Geliştirilmiş Discriminator: Polimorfizm (çok biçimlilik) desteği iyileştirilmiştir.

  • YAML Desteği: ASP.NET Core artık OpenAPI dokümanını YAML formatında sunabilmektedir.

Not: OpenAPI 3.2, sorgu metodu (QUERY) desteği ve geliştirilmiş örnekler gibi ek özellikler getirmiştir.

2. ASP.NET Core'da OpenAPI Dokümantasyonu Oluşturma

.NET ekosisteminde OpenAPI dokümanı oluşturmak için üç ana yaklaşım vardır:

A. Yerleşik OpenAPI Desteği (.NET 9 ve Sonrası)

.NET 9 ve sonraki sürümlerde, ASP.NET Core yerleşik OpenAPI desteği sunmaktadır. Swashbuckle artık varsayılan şablonlarda yer almamakta, ancak topluluk paketi olarak eklenebilmektedir.

csharp

// Program.cs (.NET 9+)
var builder = WebApplication.CreateBuilder(args);

// OpenAPI servisini ekle
builder.Services.AddOpenApi();

var app = builder.Build();

// OpenAPI dokümanını endpoint olarak map et
app.MapOpenApi();

// Swagger UI (isteğe bağlı, Scalar veya Swagger UI ile)
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/openapi/{documentName}.json", "My API");
});

app.Run();

Bu yaklaşım, harici bir kütüphaneye ihtiyaç duymadan OpenAPI dokümanı oluşturmanın en hafif yoludur.

B. Swashbuckle.AspNetCore (Topluluk Paketi)

Uzun yıllardır .NET ekosisteminde standart olan Swashbuckle, hem OpenAPI JSON dokümanı oluşturur hem de Swagger UI arayüzünü sağlar.

csharp

// Program.cs (Swashbuckle ile)
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

app.UseSwagger();
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"));

C. NSwag (Açık Kaynak .NET Araç Zinciri)

NSwag, ASP.NET Core controller'larından OpenAPI spesifikasyonu oluşturabilen ve tam tersini yapabilen güçlü bir araç zinciridir.

csharp

// Program.cs (NSwag ile)
builder.Services.AddOpenApiDocument(config =>
{
    config.Title = "My API";
    config.Version = "v1";
});

app.UseOpenApi();
app.UseSwaggerUi3();

3. Swagger UI ve Etkileşimli Dokümantasyon

OpenAPI dokümanınızı görselleştirmek ve test etmek için çeşitli araçlar mevcuttur:

  • Swagger UI: En yaygın kullanılan interaktif dokümantasyon arayüzüdür. API endpoint'lerini listeleyip doğrudan test etmenizi sağlar.

  • ReDoc: Daha okunabilir, üç sütunlu bir dokümantasyon arayüzüdür.

  • Scalar: .NET 10 ile birlikte popülerlik kazanan modern bir OpenAPI UI alternatifidir.

4. OpenAPI'den Kod Üretimi (Code Generation)

OpenAPI spesifikasyonunun en güçlü yanlarından biri, otomatik kod üretimi yeteneğidir. Bir API tanımından hareketle, istemci kütüphaneleri (SDK), sunucu iskeletleri (server stubs) ve dokümantasyon otomatik olarak oluşturulabilir.

A. .NET Ekosisteminde Kod Üretim Araçları

Araç Açıklama Kullanım
Microsoft.dotnet-openapi .NET Global Tool; OpenAPI dosyasından güçlü tipli istemci (C#/TypeScript) üretir dotnet openapi add file openapi.json --code-generator NSwagCSharp
NSwag ASP.NET Core controller'larından OpenAPI oluşturur, C# ve TypeScript istemci kodları üretir NSwagStudio masaüstü uygulaması veya NuGet paketleri
Swagger Codegen OpenAPI spesifikasyonundan 40'tan fazla dilde istemci ve sunucu kodu üretir swagger-codegen generate -i openapi.json -l csharp -o ./client
Refitter OpenAPI spesifikasyonundan Refit HTTP istemci interfaceleri üreten .NET aracı ve source generator Source generator veya CLI (dotnet-refitter)
Geren OpenAPI .json dosyasından derleme zamanında typed HttpClient sınıfları üreten Roslyn source generator MSBuild AdditionalFiles ile
Dotnetify OpenAPI (swagger.json) dosyasını saniyeler içinde çalıştırılabilir C# backend projesine dönüştürür -

B. İstemci (Client) Kodu Üretme

OpenAPI spesifikasyonundan istemci kodu üretmek, API tüketimini tip güvenli hale getirir ve manuel HTTP çağrısı yazma ihtiyacını ortadan kaldırır.

bash

# Microsoft.dotnet-openapi ile C# istemci üretme
dotnet tool install -g Microsoft.dotnet-openapi
dotnet openapi add file https://api.example.com/openapi.json --code-generator NSwagCSharp

bash

# Swagger Codegen ile C# istemci üretme
swagger-codegen generate -i openapi.json -l csharp -o ./GeneratedClient

csharp

// Refitter ile Refit interface üretimi (source generator)
// Proje dosyasına ekle:
<PackageReference Include="Refitter" Version="*" PrivateAssets="all" />
<AdditionalFiles Include="openapi.json" />
// Derleme sonrası Refit interface'leri otomatik oluşur[reference:38]

C. Sunucu (Server) Kodu Üretme

OpenAPI spesifikasyonundan sunucu iskeleti (stub) oluşturmak, API geliştirmeyi hızlandırır.

  • Swagger Editor üzerinden Generate Server → ASP.NET Core seçeneği ile sunucu kodu üretilebilir.

  • Swagger Codegen ile aspnetcore hedefi kullanılarak sunucu iskeleti oluşturulabilir.

5. OpenAPI Kullanımının Avantajları

  • Dokümantasyon Otomasyonu: API dokümantasyonu kodla birlikte güncel kalır.

  • Tip Güvenliği: Otomatik üretilen istemci kodları, derleme zamanında tip kontrolü sağlar.

  • Hızlı Prototipleme: Sunucu iskeletleri ile API geliştirmeye hızlı başlanır.

  • Dil Bağımsızlığı: Aynı OpenAPI dosyası, farklı dillerde istemci/sunucu kodu üretmek için kullanılabilir.

  • Ekosistem Entegrasyonu: Postman, Insomnia, SwaggerHub gibi araçlar OpenAPI dosyalarını içe aktarabilir.

6. .NET Ekosisteminde OpenAPI için En İyi Pratikler

  1. Dokümanı Güncel Tutun: OpenAPI dosyasının API davranışıyla her zaman eşleştiğinden emin olun.

  2. Versiyonlama: API sürümlerini OpenAPI dokümanında info.version alanı ile belirtin.

  3. Örnekler Ekleyin: example ve examples alanları ile API tüketicilerine rehberlik edin.

  4. Güvenlik Tanımları: securitySchemes ile kimlik doğrulama mekanizmalarını (JWT, API Key, OAuth2) tanımlayın.

  5. İstemci Kodunu Otomatik Üretin: CI/CD pipeline'ında OpenAPI'den istemci kodu üretmeyi otomatikleştirin.

  6. OpenAPI 3.1 veya 3.2 Kullanın: JSON Schema uyumluluğu ve yeni özelliklerden yararlanmak için güncel sürümleri tercih edin.

Sonuç

OpenAPI (Swagger), modern API geliştirmenin vazgeçilmez bir parçasıdır. ASP.NET Core ile yerleşik veya Swashbuckle/NSwag aracılığıyla OpenAPI dokümanı oluşturulabilir; Swagger UI, ReDoc veya Scalar ile etkileşimli hale getirilebilir. En önemlisi, OpenAPI spesifikasyonundan NSwag, Refitter, Geren veya Swagger Codegen gibi araçlarla otomatik olarak tip güvenli istemci kodları, sunucu iskeletleri ve SDK'lar üretilebilir. Bu yaklaşım, geliştirme hızını artırır, dokümantasyonu güncel tutar ve API tüketimini standartlaştırır.

Tüm yazılar