ASP.NET Core Web API ve Swagger

Merhaba,

ASP.NET Core ile birlikte çeşitli projeler geliştirebiliyoruz. Bu proje tiplerinden en önemlisi ise API projeler. API nedir? ASP.NET Core Web API bize neler sağlar? ve Swagger isimli ürün ile API’nin nasıl bir ilgisi olacak bu makalede bunları incelemeye çalışacağız.

Nedir bu API dedikleri?

API uzun adıyla Application Programming Interface, temel olarak farklı türden uygulamaların beraber çalışmalarını sağlayan yazılımlar olarak düşünülebilir. API uygulamalar arasında veri alışverişlerini sağlar. Tabii bu veri transferleri sırasında güvenlik, yetkilendirme ve yine genel uygulama mantığında kullanılan işlemlerin hepsi kullanılmaktadır. En belirgin fark ise API uygulamalarının bir arayüzlerinin (GUI) olmamasıdır.

API üzerinden alınan değerler ile -bazen de değer almadan- yapılan işlemlerin sonuçları (database crud, başka uygulamalardan veri almak vb.) başka uygulamalar tarafından okunabilir şekilde verilebilmektedir. Böylelikle farklı platformlarda çalışan, farklı teknolojilere sahip uygulamaların tamamı aynı API’ye veri gönderebilir ve sonuçları alarak kendi yapıları üzerinde değerlendirebilirler.

API teknolojilerinin günümüzde en bilinen kullanım yeri mobil uygulamaların arka tarafında bulunan servisler (backend) olarak karşımıza çıkar. Mobil uygulama ister IOS ister Android platformunda olsun aynı API üzerinden verileri okur ve işlemlerini yapabilir.

ASP.NET Core Web API ne oluyor o zaman ?

API aslında bir teknoloji, bir yapı olarak bahsedilen bir kavram. Tabii ki bir API uygulaması farklı diller ile yazılabilmektedir. Biz bu makalemizde ASP.NET Core ile bir API uygulamasının nasıl oluşturulacağının inceleyeceğiz.

ASP.NET Core ile ilgili daha içerikli bilgi için Nedir bu ASP.NET Core ? makalesini inceleyebilirsiniz.

ASP.NET Core Web API projemizi oluşturalım ardından Swagger nedir ? Nasıl kullanılır? İncelememize devam edelim.

Projemiz ile çalışmak için Visual Studio Code kullanacağız. Yeni bir ASP.NET Core projesi oluşturuyoruz. Projemiz için .NET Core CLI’den yaralanacağız. İlk önce webapi projemizi aşağıdaki gibi oluşturuyoruz.

Ardından uygulamamızı test etmek için dotnet run komutunu çalıştıralım ve oluşturulmuş olan API’mizi kontrol edelim.

Uygulamızın adresini komut çalıştırıldıktan sonra görebilmekteyiz. http://localhost:5000 bu adres üzerinden tarayıcımız ile uygulamamızı kontrol edebiliriz. Yeni oluşturulan iskelet uygulama içerisinde test edebilmemiz veya yeni başlayanlar için örnek olması açısında bir Controller hazır bir şekilde gelecektir. (WeatherForecast) bu controller üzerinden API’mizi test edebiliriz.

Bir başka test yöntemi ise API geliştiricilerini sıklıkla kullandığı **POSTMAN **uygulamasıdır. POSTMAN uygulamasını buradan indirebilirsiniz. POSTMAN, API’ler ile çalışmak için kullanılan bir uygulamadır. Tarayıcılar üzerinden API verilerini almanın veya isteklerin gönderilmesinin zorluğunu yaşamamak için POSTMAN kullanılmaktadır. POSTMAN üzerinden de API üzerinden bulunan controller aşağıdaki şekilde bize verileri getirmektedir.

Dilerseniz şimdi bir kod yazmaya geçebiliriz. Şimdi kendimiz bir controller oluşturarak buradan verilerin (statik olarak) gelmesini sağlayacağız. Ardından API üzerinde oluşturduğumuz bu controller’ı test edip Swagger ile çalışmamıza bakabileceğiz.

Yeni controller oluşturmak için Visual Studio Code kullanacağız projemizi Visual Studio Code ile açmak için yine komut satırı üzerinde code . yazmamız yeterli olacaktır.

Projemiz Visual Studio Code ile ilk açıldığı zaman uygulama projemizi build ve debug edebilmek için gerekliliklerin yüklenmesini isteyip / istemediğimizi bize soracaktır. Bu kısımda **Yes **butonu ile gerekliliklerin yüklemesini tamamlayabiliriz.

Yeni oluşturacağımız Controller temel araç bilgilerini API üzerinden servis edecektir. Bunun için ilk önce araç modelimizi oluşturmalıyız. Sol dosya gezgini üzerinden **Models **isminde yeni bir klasör açarak Car.cs isminde bir dosya oluşturuyoruz. Ardından bu dosyaya modelimizi yazıyoruz.

namespace ASPNETCoreSwagger.Models 
{
    public class Car
    {
        public int Id { get; set; }
        public string Brand { get; set; }
        public string Model { get; set; }
        public int Year { get; set; }
    }
}

Ardından **Controllers **klasörü altında yeni bir dosya oluşturarak adına **CarController.cs **veriyoruz. Burada bir araç listesi ile ilgili işlemler yapacağız ve bu işlemleri API üzerinden servis edeceğiz.

CarController.cs dosyamız ise aşağıdaki gibi olacaktır.

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using ASPNETCoreSwagger.Models;
namespace ASPNETCoreSwagger.Controllers
{
  [ApiController]
  [Route("[controller]")]
  public class CarController : ControllerBase
  {
    [HttpGet]
    public IEnumerable<Car> Get()
    {
      return GetCars();
    }
    [HttpGet("{id}", Name = "Get")]
    public Car Get(int id)
    {
      return GetCars().Find(e => e.Id == id);
    }
    [HttpPost]
    [Produces("application/json")]
    public Car Post([FromBody] Car car)
   {
      return new Car() { 
                         Id = car.Id, 
                         Brand = car.Brand, 
                         Model = car.Model, 
                         Year = car.Year };
   }
    [HttpPut("{id}")]
    public void Put(int id, [FromBody] Car car)
    {
    }
    [HttpDelete("{id}")]
    public void Delete(int id)
    {
    }
    private List<Car> GetCars()
    {
      return new List<Car>() {
                       new Car() { 
                                  Id = 1, 
                                  Brand = "Toyota", 
                                  Model = "Auris", 
                                  Year = 2012},
                       new Car() { 
                                   Id = 2, 
                                   Brand = "BMW", 
                                   Model = "3.20", 
                                   Year = 2019},
                       new Car() { 
                                   Id = 3, 
                                   Brand = "Renault", 
                                   Model = "Clio", 
                                   Year = 2020}
                               };
   }
 }
}

Şimdi oluşturduğunuz Controller’ı kullanarak API’mizi test edebilir.

Visual Studio Code üzerinden açacağımız terminal üzerinde dotnet run yazarak uygulamamızı çalıştıralım. POSTMAN üzerinden hem liste hem de istediğimiz araç bilgisine ulaşabilmekteyiz.

Buraya kadar API’mizin oluşturulması ile ilgili çalışmalar yaptık. Peki bu API’yi kullanacak olan uygulamaların geliştiricilerine API ve çalışması ile ilgili bilgiyi nasıl ileteceğiz ? Diyelim ki mobil uygulama geliştiren bir takımın içerisinde backend servislerini geliştiriyoruz. Mobil uygulamaları geliştiren ekip üyelerine bu geliştirdiğimiz metodların nasıl çalıştığı hakkında bilgi vermemiz gerekir. Hem metodların çağırılmaları hem de geri dönen cevap bilgilerinin doküman haline getirilip iletilmesi en sağlıklı yöntem olacaktır.

Böyle bir durumda her metodu tek tek belirli bir formatta yazmak elbette yorucu olacaktır. Bu durumu daha kolay ve pratik hale getirmek için **Swagger **ideal bir ürün olarak karşımıza çıkıyor.

**Swagger **eklediğimiz projemizde oluşturduğumuz metod bilgilerini otomatik olarak dokümante eder. Bu metod bilgileri her istekleri (request) hem de cevap (response) bilgileri ile birlikte API’mizi kullanmak isteyen uygulama geliştiriciler tarafından görüntülenebilir.

**Swagger **iki bölümden oluşmaktadır. Bunlardan ilki ve en önemlisi Swagger Specification’dır. Burada **Swagger **tarafından otomatik olarak oluşturulan bir swagger.json dosyası mevcuttur ve her API güncellemesinde bu dosya güncellenerek API içerisinde bulunan metodlarımızın bilgilerini barındırır.

İkinci bölüm ise Swagger UI olarak adlandırılmaktadır. Burada da API üzerinde bulunan metodların görsel olarak bilgilerini alabiliriz. Metodların çalışmalarını, verdikleri cevapları ve aldıkları parametre bilgileri görüntülenebilir. Ayrıca basit bir şekilde metodları çalıştırabilir ve metod cevaplarının UI üzerinden alabiliriz. Swagger UI üzerinden özellikle bir uygulama yazarak API üzerinden metodların test edilmesine gerek kalmayacaktır.

Şimdi oluşturduğumuz uygulamamıza Swagger’ı nasıl uyarlarız ona bakalım.

Swagger üç bileşenden oluşmaktadır. Tüm bu bileşenleri tek **nuget **paketi şeklinde uygulamamıza almamız mümkündür.

Bu bileşenler;

• Swashbuckle.AspNetCore.Swagger

• Swashbuckle.AspNetCore.SwaggerGen

• Swashbuckle.AspNetCore.SwaggerUI

Swagger paketini yükleyelim

Paketi projemize eklemek için Visual Studio Code terminal ekranından aşağıdaki komutu yazmamız yeterli olacaktır.

dotnet add package Swashbuckle.AspNetCore

Ardından paket uygulamamıza indirilmiş ve yüklenmiş olacaktır.

Swagger’ın uygulamamıza uyarlanması için ilk önce Startup.cs içerisinde bulunan **ConfigureServices **metoduna aşağıdaki satırları eklememiz gerekmektedir.

Yine Startup.cs içerisinde bulunan **Configure **metoduna da aşağıdaki satırları ekliyoruz.

Şimdi Visual Studio Code terminal ekranından uygulamamızı çalıştırıp Swagger uyarlamasının test edebiliriz. Bunun için terminal ekranına dotnet run yazmamız gerekmektedir.

Ardından tarayıcımızdan veya POSTMAN üzerinden https://localhost:5001/swagger/v1/swagger.json adresine girersek Controller bazlı metod bilgilerimizin json formatında geldiğini görebiliriz.

Peki bir UI bileşeninden bahsetmiştik. Şimdi de bu UI bileşenini nasıl kullanacağımıza bakalım.

Projemiz çalışırken https://localhost:5001/swagger/index.html adresine tarayıcımız üzerinden girdiğimiz zaman API Bilgileri başlıklı bir sayfa açılacak ve metot bilgilerimizi görüntüleyebileceğiz.

Swagger UI üzerinden metodların bilgilerini metot isimlerine tıklayarak alabiliriz.

Burada araç bilgilerini listelediğimiz metodumuzun özelliklerini görüyoruz. **Parameters **bölümü metodumuzun parametre bilgilerini, **Responses **bölümü ise API metodu üzerinden dönen cevap (response) hakkında bilgi vermektedir. Sağ üst kısımda bulunan Try it out butonu ile API metodunu çalıştırabilir dönen bilgileri de görebiliriz.

Swagger UI üzerinde metodlarımızın açıklamalarını da görüntülememiz mümkündür. Bu şekilde metodlarımızı inceleyen uygulama geliştiricilere anlamlı açıklamalar ile metodun görevini anlatmamız mümkün olmaktadır.

Bunun için uygulamamızın **csproj **dosyasına **(bizim uygulamamız için dosya adı ASPNETCoreSwagger.csproj) **aşağıda bulunan satırları eklememiz gerekmektedir.

Ardından Startup.cs dosyasında bulunan **ConfigureServices **metoduna da aşağıdaki satırları ekliyoruz.

Artık API metodlarımıza açıklamalar ekleyebilir ve bu açıklamaların Swagger UI üzerinden görüntülenmesini sağlayabiliriz. Metodlarımıza nasıl açıklama ekleyeceğimizin örneğini aşağıda bulabilirsiniz. Ardından Swagger UI üzerinden metot açıklamasını görüntüleyebilirsiniz.

Projemizi yeniden çalıştırıp Swagger UI üzerinden kontrol ettiğimiz zaman metod açıklamasının geldiğini görebiliriz.

Görüldüğü gibi Swagger API projelerimizde dokümantasyon işlemlerini bizler için hızlı bir şekilde çözmektedir. API’den yararlanacak olan yazılım geliştiricilerin doğru bilgilere ulaşması Swagger ile daha rahat olacaktır.

Başka bir makale ile yeniden görüşmek üzere.

https://www.yazilimbilisim.net/c-sharp/asp-net/api-nedir/ https://code-maze.com/swagger-ui-asp-net-core-web-api/

Originally published at http://onurkarakus.wordpress.com on August 29, 2020.