Core 3.0 ile Swagger Kullanmak
{
var ademOlguner = @“Herşey iki süslü parantez açıp Hello World yazarak başladı. İlişkimizin buralara kadar geleceğini tahmin bile edemezdim :)
Bazı mesleklerin emekliliği yoktur derler sanırım programlama da bu mesleklerden biri. Çok eski sayılmam ama uzunca bir süre programlama dünyasında kalmayı istiyorum. Torunlarıma ‘deden ne iş yapardı’ diye sorduklarında ‘bilgisayar programcısı’ dediklerini hayal ediyorum ve ufak bir tebessümle tatlı girizgahı sonlandırıyorum”;
}
Projelerde karşılaştığım ve kullandığım bir teknoloji olan Swagger hakkında öğrendiklerimden ve araştırmalardan yola çıkarak Swagger nedir, nasıl kurulur, nasıl konfigüre edilir, ve nasıl kullanılır gibi soruların cevaplarını bulmaya çalışacağız.
Swagger’a geçmeden önce API hakkında birkaç şey söylemek gerekiyor .
API (Application Programming Interface), bir uygulamaya ait işlevlerin başka bir uygulamada da kullanılabilmesi için oluşturulmuş bir arayüzdür.
Mobil uygulamaların yaygınlaşması , akıllı cihazların günlük hayatımızda kullanımının artması ile API’ler artık projelerimizin olmazsa olmazı haline gelmeye başladı.
API hizmetinin en zahmetli noktası dökümantasyon işlemidir. Dökümantasyon API için olmazsa olmazıdır, beraberinde de iş yükü getirmektedir. Dökümantasyonda metot isimlerinin, metot imzalarının , input ve output parametrelerinin kullanıcılara açık ve net bilgiler vermesi gerekmektedir. API lerin güncellenmesi durumunda dökümantasyonu da aynı şekilde güncel tutmak gerekmektedir ki işte tam bu noktada imdadımıza Swagger yetişir.
Swagger ?
“ Swagger bahsetmiş olduğumuz API (Rest API) hizmetlerinin mesaj yapısı ve nasıl kullanılacağı ile ilgili standartlaşmış arayüz sunan bir dokümantasyon aracı olarak düşünülebilir”.
Şimdi Entity, Data Access ve Business katmanları yazılmış bir API projesini düşünelim. Bu API için önemli hususlardan birisi de sözleşmesinde sunduğu operasyonların test edilmesidir. Bunu tek satır kod yazmadan yapabiliriz desem! Meraklandınız değil mi?
WebUI katmanını yazmadan , Mobil katmanını kodlamadan test yapabileceğiz demek! O nasıl oluyor ki :)
Şimdi Swagger ile API’lerimizi çalıştırarak testlerin başarılı olup olmadığını backend tarafında olası hataları arayüz katmanını yazmadan da tespit edebileceğimiz anlamına geliyor. Kulağa hoş geliyor gibi.
Ufak bir örnek üzerinden anlatmaya çalışacağım.
- Bir adet Core 3.0 WebAPI projesi oluşturacağız.
- Bir adet api controller (StudentsController) oluşturacağız.
- Bir adet de Student nesnesi oluşturacağız.
- StudentsController içerisinde Get,Post,Put,Delete işlemlerine örnek olması amacıyla birer adet metot oluşturacağız.
- appsettings.json dosyasında Swagger ayarlarını GetSection ile okuyacağız.
- ProducesResponseType ile Swagger’ı biraz daha kullanıcı dostu haline getirip zenginleştireceğiz.
- Metotların ne yaptığına dair bilgileri Swagger ortamında sağlayacağımız yorum satırları için düzenlemeler yapacağız.
- pragma warning disable ile uyarıların nasıl dikkate alınmayacağı gibi işimizi kolaylaştıracak ayarlar yapacağız.
1- İlk olarak Web API projemizi oluşturuyoruz.
(File => New => Project)
2- Student sınıfını oluşturalım.
- Dört adet property ekliyoruz,
- List<Student> bir adet static metot oluşturuyoruz. (test datası için)
3- StudentsController adında bir adet api controller ekliyoruz.
(API Projesi => Controller Klasörü sağ tık=> add => Controller => API Controller Empty) yolunu izleyerek ekleyebiliriz.
HTTP Get metoduna cevap verecek ve tüm öğrenci listesini döndürecek GetList isimli bir metot ekliyoruz, geri dönüş değeri ActionResult tipinde ayarlıyoruz.
4- Swagger Kurulumu.
API Projesi sağ tık => Manage Nuget Packages
Manage Nuget Packages browse sekmesinde Swashbuckle.AspNetCore olarak arıyoruz. Swashbuckle.AspNetCore eklentisi içerisinde SwaggerGen, SwaggerUI ve Swagger gibi dependencies leri de barındırır.
API Projesi sağ tık => Manage Nuget Packages
Manage Nuget Packages browse sekmesinde Microsoft.OpenApi eklentisini kuruyoruz.
5- Startup.cs dosyası içerisinde Swagger konfigürasyon işlemleri ve middleware ekleyelim.
Startup.cs içerisinde ConfigureServices metoduna ekliyoruz ;
Startup.cs içinde Configure metoduna Swagger middleware’i ekliyoruz;
Swagger ile ilgili ayarlamaları yaparken SwaggerDoc içerisindeki name alanı ile Swagger.EndPoint noktasındaki isimlendirme eşlenik olmalı aksi durumda hata alacaktır.
SwaggerGen ile Swagger yapılandırma işlemi, lisans ve açıklama gibi bilgileri eklemek için kullanılmaktadır.
[ AddSwaggerGen ]
Startup.cs içerisinde ayarlamalarımızı yapıyoruz.
StudentsController içerisinde yazılan metodun çıktısı;
6- Şimdi response işlemlerini biraz daha iyileştirerek devam ediyoruz.
[ProducesResponseType(201)], [ProducesResponseType(400)] gibi Attribute yardımı ile kullanıcıya çıktı verirken daha anlaşılır daha okunabilir ve hata durumlarında kullanıcı bilgilendirilmesi gibi işlemleri de bu şekilde kullanabiliriz. Düzenlemelerden sonra Swagger çıktısı alttaki gibi olacaktır.
7- Açıklama alanları
Kod blokları için yorum satırı (comment) yazarız. Yorum satırları çalıştırılacak olan metot hakkında bizlere bilgi sağlamaktadır. Metotun ne işe yaradığı istenen parametreler ve geri dönüş değerleri gibi.
Yorum satırı alanları metotların üstünde (üç slash ///) şeklinde yazarız.
/// <summary>
///
/// </summary>
/// <returns></returns>
Swagger içerisinde bu alanları etkinleştirmek için düzenlemeleri yapmamız gerekmektedir.
var xmlFile =$”{Assembly.GetExecutingAssembly().GetName().Name}.xml”;
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
Konfigürasyon ayarları sonrası açıklama ve yorum satırı alanları görülecektir.
8- pragma warning disable
Bazı kod bloklarında görmezden gelinebilecek uyarılar için .csproj dosyasında ProperyGroups içerisine uyarı kodlarını eklenir.
<NoWarn>$(NoWarn);1591</NoWarn>
Örnek olması açısından program.cs içerisindeki kod bloğunu bu şekilde uyarı alanı olarak ayarlayalım.
Son olarak startup.cs dosyası içerisinde yazmış olduğumuz Swagger ile ilgili parametre değerlerini appsettings.json dosyasında okunabilir hale getirelim.
- appsettings.json içerisinden konfigürasyon parametrelerini GetSection metodu yardımı ile okuyalım.
- Swagger middleware için json dosyasında okuma yapalım.
UseSwaggerUI içerisindeki SwaggerEndPoint alanını string Format şeklinde yazalım.
“SwaggerName”: “CoreSwaggerWebAPI-Swagger”
“SwaggerEndpoint”: “/swagger/CoreSwaggerWebAPI-Swagger/swagger.json”“SwaggerEndpoint”: “/swagger/{0}/swagger.json”
{0} ve “SwaggerName” attribute alanı aynı isimde olmalıdır.İsimlendrime alanını tekrarlı yazmamak için tek bir tanımlama yapıp gereken yerde aynı değeri okuyarak kullanalım.
Tüm ayarlamaları yaptıktan sonra örnek için bir kaç metot yazıp tekrar çalıştırıyoruz.
Şema(Schema) içerisinde API istek ve cevaplarında (request — response) ve kullanılan nesneler (Class, Dto vb…) görünecektir.
Dilim döndüğünce Swagger hakkında birşeyler aktarmaya çalıştım umarım faydalı olmuştur. Başka bir yazıda görüşmek dileğiyle…
