OpenAPI ve Swagger ile API Dokümantasyonu

Bir API ne kadar iyi yazılırsa yazılsın, nasıl kullanılacağı bilinmiyorsa değeri sınırlı kalır. OpenAPI, REST API'lerin uç noktalarını, parametrelerini, istek ve yanıt modellerini makinelerin ve insanların okuyabileceği standart bir biçimde tanımlayan belirtimdir.

OpenAPI ve Swagger farkı

OpenAPI: API'yi tanımlayan standart (JSON veya YAML belgesi).
Swagger: Bu standart etrafında gelişen araçların adı; örneğin belgeyi etkileşimli bir web sayfası olarak gösteren Swagger UI.

Belirtimin önceki adı Swagger olduğu için iki terim sık sık birbirinin yerine kullanılır.

Ne sağlar?

Etkileşimli belge: Geliştiriciler API'yi tarayıcıdan deneyebilir.
İstemci kodu üretimi: C#, TypeScript ve birçok dil için istemci kütüphaneleri otomatik üretilebilir.
Sözleşme testi: API'nin belgeyle uyumlu olup olmadığı kontrol edilebilir.
Entegrasyon kolaylığı: İş ortakları API'yi daha hızlı entegre eder.

ASP.NET Core'da

.NET 9 ile birlikte ASP.NET Core, OpenAPI belgesi üretimini yerleşik olarak destekler:

builder.Services.AddOpenApi();
var app = builder.Build();
app.MapOpenApi(); // /openapi/v1.json

Belgeyi görüntülemek için tercih ettiğiniz bir arayüz aracı eklenebilir. Daha önce şablonlarda yer alan Swashbuckle ise ayrı bir paket olarak kullanılmaya devam edilebilir.

İyi dokümantasyonun özellikleri

Her uç noktanın ne yaptığını anlatan kısa bir açıklama.
Parametrelerin ve alanların anlamı, birimi ve sınırları.
Örnek istek ve yanıtlar.
Hata kodlarının anlamı.
Kimlik doğrulama yönteminin açıklaması. Bkz. JWT kimlik doğrulama.
Sürüm bilgisi. Bkz. API versiyonlama.

Güvenlik

Etkileşimli API belgesini canlı ortamda herkese açık bırakmak, saldırganlara API'nin haritasını vermek anlamına gelebilir. İç API'lerde belge yalnızca geliştirme ortamında veya kimlik doğrulama arkasında sunulmalıdır.

Kod önce mi, belge önce mi?

Kod önce: Kod yazılır, belge otomatik üretilir. Hızlıdır.
Belge önce: Önce OpenAPI belgesi tasarlanır, ekipler buna göre çalışır. Birden fazla ekibin paralel çalıştığı projelerde avantajlıdır.

Sık sorulan sorular

OpenAPI yalnızca REST için mi?

Evet, HTTP tabanlı API'ler için tasarlanmıştır. GraphQL'in kendi şema sistemi vardır. Bkz. GraphQL mi REST mi.

Belgeyi güncel tutmak zor mu?

Kod önce yaklaşımında belge koddan üretildiği için kendiliğinden güncel kalır; açıklamaları güncel tutmak ise ekibin sorumluluğundadır.

Sonuç

İyi belgelenmiş bir API, entegrasyon süresini kısaltır ve destek yükünü azaltır. API geliştirme ve entegrasyon projeleriniz için iletişime geçebilirsiniz.