.NET Core Swagger

.NET Core ile REST tabanlı web servislerine doküman hazırlamak için kullanılan swagger paketi ile ilgili bilgiler yer alıyor.

REST tabanlı web servislerin en önemli özelliği esnek bir yapısının olmasıdır.

REST ile ilgili detaylı bilgi için REST Nedir? yazıma bakmalısın.

Esnek olması, standartların geliştiriciler tarafından belirlenmesi beraberinde bazı sorunları getirmektedir.

Bu sorunlardan en önemlisi REST API dokümanı olduğu söylenebilir.

REST tabanlı web servis her ne kadar best pratices olarak adlandırılan kalıplaşmış kurallara göre iyi hazırlansa da dokümantasyonu olmayan bir REST API kara kutu olacaktır.

REST API’nin kara kutu olması servisinin kullanılabilir olmasını azaltacaktır.

Dokümantasyon hazırlama

Web servis için ayrı bir Word, PDF veya Web tabanlı bir dokümantasyon hazırlanabilir.

Ancak REST API üzerinde yapılan değişiklik sonrası dokümantasyonun düzenlemesine ihtiyaç duyulacaktır.

Swagger kullanımı

Swagger REST tabanlı web servisler için belirli kurallara göre otomatik olarak REST API dokümantasyonu oluşturmayı sağlayan bir araçtır.

Swagger ile standartlara uygun, dokümantasyon üzerinden test edilebilir ve otomatik güncellenen REST API dokümanı oluşturabiliriz.

Swagger kurulumu

Swagger kullanımı için ilk olarak .NET Core (dotnet) CLI aracı ile webapi şablonu ile REST API projesi oluşturalım.

dotnet new webapi -o SwaggerProjesi

Projeye Swashbuckle.AspNetCore paketini ekleyelim.

dotnet add package Swashbuckle.AspNetCore

NOT: .NET 5 sonrasında paket webapi şablonu ile birlikte gelmektedir.

Paketi ekledikten sonra Startup.cs dosyasında yer alan ConfigureServices metodu ile swagger servisini ekleyelim.

services.AddSwaggerGen(options => {
    options.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info {
        Version = "v1",
        Title = ".NET Core Swagger"
    });
});

.NET 5 sonrası ayarlar aşağıdaki gibidir.

builder.Services.AddSwaggerGen(options => {
    options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo {
        Version = "v1",
        Title = ".NET Core Swagger"
    });
});

API ile ilgili diğer bilgiler için Info sınıfında yer alan diğer alanlarda kullanılabilir.

options.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info {
    Version = "v1",
    Title = "Burada REST API başlığı yer alacak",
    Description = "Burada REST API açıklaması yer alacak",
    TermsOfService = "Burada REST API kullanım şartları yer alacak",
    Contact = new Swashbuckle.AspNetCore.Swagger.Contact {
        Name = "Yusuf Sezer",
        Email = "[email protected]",
        Url = "https://www.yusufsezer.com"
    },
    License = new Swashbuckle.AspNetCore.Swagger.License {
        Name = "MIT",
        Url = "https://opensource.org/license/mit/"
    }
});

.NET 5 sonrası ayarlar aşağıdaki gibidir.

options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo {
    Version = "v1",
    Title = ".NET Core Swagger",
    Description = "Burada REST API açıklaması yer alacak",
    TermsOfService = new Uri("https://www.yusufsezer.com"),
    Contact = new Microsoft.OpenApi.Models.OpenApiContact {
        Name = "Yusuf Sezer",
        Email = "[email protected]",
        Url = new Uri("https://www.yusufsezer.com")
    },
    License = new Microsoft.OpenApi.Models.OpenApiLicense {
        Name = "MIT",
        Url = new Uri("https://opensource.org/license/mit/")
    }
});

Servis eklendikten sonra Startup.cs dosyasında yer alan Configure metodu ile servis (middleware-orta katman) etkin hale getirilir.

app.UseSwagger();

app.UseSwaggerUI(options => {
	options.DocumentTitle = "Swagger API doküman başlığı";
	options.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger API başlığı");
});

.NET 5 sonrası webapi şablonunda varsayılan olarak gelen kodlar düzenlenir.

if (app.Environment.IsDevelopment()) {
    app.UseSwagger();
    app.UseSwaggerUI(options => {
        options.DocumentTitle = "Swagger API doküman başlığı";
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger API başlığı");
    });
}

Gerekli olan ayarları yaptıktan sonra projeyi çalıştıralım.

dotnet run

veya

dotnet watch run

Proje çalıştırıldıktan sonra /swagger adresi ile dokümantasyona ulaşabilirsiniz.

Swagger aracının diğer bir önemli özelliği ise dokümantasyon adresinden REST API kullanımına imkan vermesidir.

Herhangi bir REST API bölümünde yer alan Try it out alanı ile REST API kullanılabilir.

Swagger dokümanına komut yorumları eklemek için ProjeAdi.csproj dosyasına aşağıdaki ayarlar eklenir.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <DocumentationFile>SwaggerProjesi.xml</DocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

AddSwaggerGen içerisine aşağıdaki komutlar eklenerek yorumlar swagger dokümanına dahil edilir.

var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments(xmlPath);

NOT: Yorumların görünmesi için metotlara yorum eklenmesi gerekir.

NOT2: Metotlara eklenen yorumlar otomatik olarak dokümana eklenecektir.

Swagger özelleştirme

Swagger paketi dokümantasyon adresi, sayfa stili gibi çeşitli doküman sayfası ayarlarının özelleştirilmesine imkan verir.

Doküman adresini değiştirmek için RoutePrefix özelliği kullanılır.

app.UseSwaggerUI(options => {
	...
	options.RoutePrefix = "dokuman";
});

Stil dosyası eklemek için InjectStylesheet metodu kullanılır.

app.UseSwaggerUI(options => {
	...
	options.InjectStylesheet("/stil-yolu/stil.css");
});

JavaScript komut dosyası eklemek için InjectStylesheet metodu kullanılır.

app.UseSwaggerUI(options => {
	...
	options.InjectJavascript("/komut-yolu/js-komut.js");
});

Ayrıca yetkilendirme, swagger nitelikleri için çeşitli ayarlar yer alır.

Bu ayarların kullanımı için Swashbuckle.AspNetCore dokümantasyonuna bakmak faydalı olacaktır.

.NET Derslerine buradan ulaşabilirsiniz.

Hayırlı günler dilerim.