.Net Core Üzerinde Swagger

Selamlar,

Bu makalede doğan bir ihtiyaca göre kullandığım teknolojilerden, Swagger üzerine konuşacağız. Şirket içinde kullanılan ya da dışarıya açılan WebServislerinin, bazen anlaşılması zor olabilir. Post ve Get methodları hangileridir? Post’da istenen model ve propertyler nelerdir? Get’de istenen parametreler nedir? Geri dönüş değerleri nelerdir? Bu ve bunun gibi ihtiyaçlar için detaylı bir dökümanın hazırlanması ve her yeni method’da ilgili dökümanın güncellenerek paylaşılması gerekmektedir. İşte bu noktada Swagger devreye girmektedir. Gelin hep beraber bir örnek üzerinde swagger’ı canlı canlı inceleyelim.

Okulların yeni başladığı bu dönemde .Net Core WebApi bir SchollService projesi oluşturalım.

Bu projede amaç sınıflar ve öğrencilerin sorgulandığı ve güncellendiği bir webapi servisi oluşturmaktır.

Models:

  • Class.cs:

  • Student.cs

Şimdi sıra Bussines’ın döndüğü Data tarafında.

DAL:

  • ISchollService: Yapılacak tüm işler, bir interface altında toplanmıştır.

  • SchollService: Datalar, static bir listeden örnek amaçlı çekilmektedir. Okul ve öğrenci listeleme, ya da filitreleme gibi işlemlerin yapıldığı örnek amaçlı birden çok servis oluşturulmuştur. Ayrıca yeni öğrenci ve sınıf girişinin yapıldığı iki “Post” servis yazılmıştır.

Şimdi sıra geldi WebApi servisini oluşturmaya:

SchollController.cs: Aşağıda görüldüğü gibidir.

  • GetAllClass(): Tüm sınıfların çekildiği method “[HttpGet(“GetAllClass”)]” şeklinde routing amaçlı tanımlanmıştır. Dönüş tipi ==>”List<Class>”‘dır.
  • GetAllStudents(): Tüm öğrencilerin çekildiği method “[HttpGet(“GetAllStudents”)]” şeklinde tanımlanmıştır. Dönüş tipi ==>”<List<Student>>”‘dır.
  • GetClassByID(int id): Bir sınıfın “id” değerine göre çağrıldığı bir methoddur. “[HttpGet(“GetClassByID/{id}”)]” şeklinde tanımlanmıştır. Dönüş tipi ==>”Class”‘dır.
  • GetClassByName(string name): Bir sınıfın “name” yani adına göre çağrıldığı bir methoddur. ” [HttpGet(“GetClassByName/{name}”)]” şeklinde tanımlanmıştır.  Dönüş tipi ==>”Class”‘dır.
  • GetStudentByClass(int classID) : Bir öğrencinin “classID” değerine göre çağrıldığı bir methoddur. “[HttpGet(“GetStudentByClass/{classID}”)]” şeklinde tanımlanmıştır. Dönüş tipi ==>”List<Student>”‘dır.
  • GetStudentByID(int id) : Bir öğrencinin “id” değerine göre çağrıldığı bir methoddur. “[HttpGet(“GetStudentByID/{id}”)]” şeklinde tanımlanmıştır. Dönüş tipi ==>”Student”‘dır.
  • GetStudentByName(string name) : Bir öğrencinin “name” yani adına göre çağrıldığı bir methoddur. “[HttpGet(“GetStudentByName/{id}”)]” şeklinde tanımlanmıştır. Dönüş tipi ==> “Student”‘dır.
  • AddStudent([FromBody] Student student) : Yeni bir öğrencinin kaydedildiği methodur. “[HttpPost(“AddStudent”)]” şeklinde tanımlanmıştır.
  • AddClass([FromBody] Class _class): Yeni bir sınıfın kaydedildiği methoddur. “[HttpPost(“AddClass”)]” şeklinde tanımlanmıştır.

Bu kadar methodun, başka biri kullanıcı tarafından kolaylıkla kullanılabilmesi için, Swagger .Net Core ortamına aşağıdaki komut ile eklenir.

Sıra geldi .Net Core Ortamında Swagger’ın Startup.cs’de tanımlanmasına.

Startup.cs/ConfigureServices:

  • “services.AddTransient<ISchollService, SchollService>()” ile servise yapılan her çağrıda yeni bir SchollService oluşturulur.
  • “services.AddSwaggerGen(c =>” : Swagger .Net Core ortamında belli configurasyonlar ile tanımlanır.
  • “c.SwaggerDoc(“CoreSwagger”, new Info” : CoreSwagger adı ile Başlık, versiyon, açıklama ve iletişim özellikleri ile service’e eklenir. Daha detaylı özellikleri sayfanın en altındaki kaynaktan edinebilirsiniz.

Startup.cs/Configure: Aşağıda görüldüğü gibi:

  • app.UseSwagger(): .Net Core projesine swagger eklenmiştir.
  • .UseSwaggerUI(c => {c.SwaggerEndpoint(“/swagger/CoreSwagger/swagger.json”, “Swagger Test .Net Core”);});: Burada swagger için kullanılacak “json” dosyasının kaydedileceği yer tanımlanmaktadır.

NOT: “/CoreSwagger” olarak yazılan kısım ==> yukarıda ConfigureServices’de tanımlanan  “c.SwaggerDoc(“CoreSwagger“, new Info” ile aynı olmak zorundadır. Swagger’ın isim parametresi olarak kullanılmaktadır.

Swagger sayfasına girilince WebApi Servisinde kullanılan methodlar, aşağıdaki gibi listelenmektedir.

Bundan sonra aşağıdaki adres satırı, bu webservisini kullanacak kişi ile paylaşılarak, kendini sürekli yenileyen, yani yeni bir servis eklendiğinde ya da değiştirildiğinde güncellenmesine gerek kalmayan bir helper olarak kullanılabilmektedir.

Authorization: Diyelim ki servislerimizde Token Authorization olsun. Bu örnekte Custom Bearer Token kullanılmıştır. Bu durumda Swagger üzerinde Token gönderen bir yapı olması gerekmektedir.
Startup.cs/ConfigureServices: Swagger’a Authorization girilecek bir alanın açılması için aşağıdaki “AddSecurityRequirement” ve “AddSecurityDefinition” tanımlamalarının, ConfigureService’e aşağıdaki gibi eklenmesi gerekmektedir.

Yukarıdaki tanımlamalar yapıldıktan sonra, Swagger ekranında aşağıda görülen istendiğinde token girilmesi için gerekli olan Authorize buttonu,  karşımıza çıkmaktadır.

Örneğin Token için “446688” girildikten sonra “GetClassByID()” methodu çağrıldığında, WebApi servisine Header ile giden request aşağıdaki gibidir. Görüldüğü gibi girilen Token ==> “Authorization: 446688” şeklinde Header’dan, WebApi servisine taşınmaktadır.

Şimdi gelin tüm Actionlar’da ilgili Token’ı yakalamak için, Custom bir TokenFilter yazalım.

TokenFilter.cs: Herbir Action’a girilmeden önce, Header ile gönderilen “Authorization” Token, aşağıda görüldüğü gibi örnek amaçlı yakalanmıştır.

İlgili TokenFilter’ın .Net Core’da kullanılabilmesi için, Startup/ConfigureService‘e aşağıdaki gibi eklenmesi gerekmektedir.

SchollController.cs: İlgili TokenFilter’ın, SchollController’ın başına aşağıdaki gibi tanımlanması ile, ilgili Controller’ın içinde geçen tüm Actionlara girilmeden önce, TokenFilter/OnActionExecuting() methodu çalıştırılır.

Güncelleme – Swagger’da Header’a Custom Fieldlar Ekleme:

Eğer yapılan request üzerinde, Header’a farklı custom alanlar konulmak istenir ve bunların Swaggerdan da girilmesi gerekir ise, IOperationFilter interface’inden türeyen yeni bir sınıfın aşağıdaki gibi oluşturulması gerekmektedir.

Aşağıdaki örnekte WebApi servisinde yapılan Request’de,  Header’a “isMobile” bool ve “senderName” string alanları eklenmiştir. Swaggerdan da “senderName” alanının girilmesi zorunlu, “isMobile” alanının girilmesi isteğe bağlı hale getirilmiştir.

Son olarak, yeni tanımlanan “OperationFilter” sınıfının, Startup.cs’de swagger’a eklenmesi gerekmektedir.

Böylece Swagger üzerinden girilen Custom bir Token’ın, WebApi servisine Header ile nasıl taşındığını, ilgili Action’a girmeden önce nasıl yakalandığını ve son olarak Header’a nasıl custome fieldların eklendiğini gördük.

Swagger, özellikle günümüzde WebApi servislerinin bolca kullanıldığı, hatta bunların dışarıda bir kaynak ile paylaşıldığı yapılarda, dökümanı ortadan kaldıran basit, pratik ve vazgeçilmez bir tooldur.

Geldik bir makalenin daha sonuna yeni bir makalede görüşmek üzere hepinize hoşçakalın.

Source Code : https://github.com/borakasmer/SwaggerOnNetCore

Kaynaklar: http://editor.swagger.io, https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/428

Herkes Görsün:

Bunlar da hoşunuza gidebilir...

6 Cevaplar

  1. Yiğit dedi ki:

    Hocam elinize sağlık. Bunu görmüştüm ama adını unutmuştum sizde görünce tekrar hatırladım. Hemde keni projeme uygulamadım.

  2. bekir dedi ki:

    Merhaba öncelikle paylaşımınız için teşekkür ederim.
    Projeyi Visual studio da açıp F5 lediğimde web api çalışmıyor Bora hocam
    Source code da bir sıkıntı olabilir mi

  3. Necmettin Yanık dedi ki:

    Enfes anlatım! 5 dakikanın altında bir sürede uygulanabilir şekilde anlatmak herkesin harcı değil. Teşekkürler!

Bir cevap yazın

E-posta hesabınız yayımlanmayacak.