ASP.NET Core 3.1 Web API – Swagger Kullanımı

Web API projeleri geliştirdiğimizde API uygulamalarımızın nasıl kullanılacağını anlatacağımız dokümantasyonlara ihtiyacımız bulunmaktadır. Bu dokümantasyonlar, API projelerimizin ne işe yaradığını, hangi parametreler ile hangi formatlarda veri gönderip alabileceğinin bilgilerini içermektedir. Bu dokümantasyonların yazılması ve güncel tutulması işlemleri zordur. Bu nedenle Web API projesinin geliştirme aşamasında otomatik olarak oluşturulması gerekmektedir. Bu noktada kullanabileceğimiz API dokümantasyon yazılımı olan Swagger’i ASP.NET Core 3.1 Web API uygulamasında nasıl kullanabileceğimizi inceleyelim. Bir önceki ASP.NET Core 3.1 Web API – Basic Authentication Kullanımı konulu makaleyi inceleyebilirsiniz.

ASP.NET Core 3.1 Web API – Swagger Örnek Projeyi Yapısı

Örnek olarak yapacağım API projesinin içeriğini şu şekilde oluşturacağım:

/item/get– Başarılı bir işlem gerçekleşirse 200 Ok durum bilgisinde tüm ürünlerin listesi getirilecek, hatalı bir işlemde 400 BadRequest sonucu döndürülecektir.

/item/get/id– Başarılı bir işlem gerçekleşirse 200 Ok durum bilgisinde, ürünler listesinden gönderdiğimiz id bilgisine göre 1 ürün getirilecektir. Hatalı bir işlemde 400 BadRequest sonucu döndürülecektir.

/item/post– Yeni bir ürün kaydı oluşturulacaktır. Başarılı bir işlem gerçekleşirse 200 Ok, hatalı bir işlemde 400 BadRequest sonucu döndürülecektir.

/item/put– Sistemde kayıtlı olan bir ürün bilgisinin güncellemesi yapılacaktır. Başarılı bir işlem gerçekleşirse 200 Ok, hatalı bir işlemde 400 BadRequest sonucu döndürülecektir.

/item/delete– Sistemde kayıtlı olan bir ürün kaydının silinme işlemi yapılacaktır. Başarılı bir işlem gerçekleşirse 200 Ok, hatalı bir işlemde 400 BadRequest sonucu döndürülecektir.

Uygulama dosyalarını aspnetcore-3-1-web-api-swagger Github adresinde bulabilirsiniz.

ASP.NET Core 3.1 Web API – Swagger Örnek Projeyi Çalıştırmak İçin Gereksinimler

ASP.NET Core uygulamalarını yerel olarak geliştirmek ve çalıştırmak için aşağıdakileri indirip yükleyin:

  • Visual Studio Code – adresinden Windows, Mac ve Linux işletim sistemlerinde çalışabilen Microsoft tarafından geliştirilip açık kaynak olarak sunulan kod editörünü indiriniz.
  • C# extension adresinden yada VS Code içersinideki eklentiler bölümünden .NET Core uygulamaları geliştirirken kolaylıklar getiren eklentiyi indiriniz.
  • .NET Core SDK – adresinden .NET Core 3.1 runtime SDK dosyasını indirip kurmalısınız.

ASP.NET Core 3.1 Web API – Swagger Örnek Projesi Nasıl Çalıştırılır?

  • Proje dosyalarını aspnetcore-3-1-web-api-swagger Github adresinden indirebilir yada klonlayabilirsiniz.
  • WebApi.csproj proje dosyasının bulunduğu klasörde bir terminal ile yada VS Code terminalinde dotnet run komutunu çalıştırın.
  • Uygulama çalıştığında http://localhost:4000 adresinden istek gönderebilirsiniz.

ASP.NET Core 3.1 Web API – Swagger Projesini Oluşturma

Proje oluşturmak için dotnet new webapi komutunu kullanıyoruz.

webapi-swagger-new-poject
dotnet new webapi

ASP.NET Core Web API – Item Entity

Path: /Entities/Item.cs

Ürün bilgilerini taşıdığımız item sınıfını oluşturuyorum. Entity yapıları uygulamanın farklı bölümlerinde veri iletimi için kullanılır. Ayrıca controller yardımıyla http yanıtlarını döndürmek içinde kullanılabilmektedir. Entities sınıfları Entityframework ile Code First yaklaşımında veritabanı tablolarını oluşturmak için kullandığımız sınıflarıdır. Not: Entities yapılarında kısıtlı veri döndürmek istendiğinde Models klasöründe ihtiyaca yönelik sınıflar kullanılmalıdır.

ASP.NET Core Web API Program

Path:/Program.cs

Program sınıfı, uygulamayı başlatmak için kullanılan bir console uygulama dosyasıdır. IHostBuilder ile Web API uygulamasının çalışmasına ihtiyacı olan web sunucusunu yapılandırır ve başlatır. ASP.NET Core uygulamasını şablondan oluşturduğumuzda varsayılan olarak gelmektedir. Builder alt özelliğinde Web API uygulamasının hangi adres ve portta başlatılacağını UseUrls ile değiştiriyorum.

Projeye Swagger Paketlerinin Eklenmesi

Terminalde dotnet add package Swashbuckle.AspNetCore satırını ekleyip çalıştırıyoruz yada farklı paket yönetimleri için buradan indirme işlemini yapınız. Bu şekilde Swagger paketlerini projemize eklemiş olmaktayız. Not: Swashbuckle.AspnetCore 5.0 versiyonuyla beraber OpenAPI 3’ü desteklenmeye başlamıştır. 

ASP.NET Core Web API Startup

Path:/Startup.cs

Startup ​​sınıfı, uygulamanın tüm isteklerin nasıl işleneceğini yapılandırdığımız sınıftır.

ASP.NET Core Web API – ItemController

Path:/Controllers/ItemController.cs

ASP.NET Core Web API – WebApi.csproj

Path:/WebApi.csproj

ASP.NET Core Web API – Swagger Sonuç

Terminalde dotnet run watch komutunu çalıştırıp projemizi localhost:4000/swagger adresine gidiyoruz.

webapi-swagger-ui
Swagger

Bir sonraki makalede görüşmek üzere.

Sosyal medyada paylaşabilirsiniz..

Bir cevap yazın

E-posta hesabınız yayımlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir