Asp.Net Core Projelerine Swagger Ekleme

Swagger biz developer'lar için oldukça önemli bir tool'dur. Server side geliştirmeler için entegre olacak client'lar veya bu endpoint'leri test etmek isteyen test ekipleri yada farklı developer takımları için döküman ve request response örnekleri hazırlamak olmazsa olmazlardan dır. .Net framework'de olduğu gibi .Net Core projelerinde de swagger kütüphanesi tam da bu gibi ihtiyaçlar için bulunmaktadır.

Swagger

Swagger'n tanımına bakacak olursak;

"Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability."

-swagger.io

Swagger yazılım dünyası tarafından oldukça büyük çapta kabul görmüş yaygın olarak kullanılan bir dynamic döküman oluşturma tool'u dur. .Net Core projeleri içinde implementasyonu oldukça basittir. 

Imp

Geliştirmekte olduğumuz .net core web api projesine nuget üzerinden Swashbuckle.AspNetCore  paketini indirip kuralım. Kurulum işlemi tamamlandıktan sonra projemizin Startup.cs sınıfı içerisinde yer alan ConfigureServices metodunda swagger'ı service olarak ekleyelim. 

public void ConfigureServices(IServiceCollection services)
{
	services.AddSwaggerGen(c =>
	{
		c.SwaggerDoc("v1", new Info { Title = "WebApplication1", Version = "v1" });
	});

        services.AddMvc();
}

Sonrasında eklediğimiz bu service'i yine Startup.cs içerisinde yer alan Configure metodunda kullanacağımızı belirtelim. 

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
	if (!env.IsProduction())
	{
		app.UseDeveloperExceptionPage();

		app.UseSwagger();

		app.UseSwaggerUI(c =>
		{
		c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApplication1");
		});
	}
}

Projenizi run ettiğinizde browser üzerinden Swagger Ui sayfasına localhost:40383/swagger şeklinde ulaşabilirsiniz ve sayfa default olarak aşağıdaki gibidir.

Yukarıda da görüldüğü gibi projemizde controller'lar içerisinde tanımlı end-point'ler, Http Request türleri, aldıkları parametreler vs gibi bilgiler yer almaktadır.

Örnek olarak POST /api/Values metodunu deneyelim. Metot isminin üzerine tıkladığımızda altta bir view expand olur ve burada request olarak göndereceğimiz parametreleri yazıp response'u alabiliriz. 

Yukarıdaki ekran görüntüsünde kısaca Values metodu string bir parametre alıyor ve geriye string bir response dönüyor. Request parametresini yazdıktan sonra Try it out butonuna tıkladığımızda aşağıdaki gibi bir ekranla karşılaşıyoruz.

 Http200 kodu ile response'u almış oluyoruz.

Özetle

Biz yazılımcılar için çile haline gelen request response örnek kodları açıklama döküman vs gibi konuları swagger ile gayet basit ve kullanışlı bir hale getirebiliriz. Swagger ile ilgili daha bir çok configuration bulunmakta. VS üzerinden XML dosya generate ederek kodlarınızın üzerinde bulunan yorumlardan yola çıkarak api dökümanı oluşturma gibi bir çok özelliği bulunmakta. Ayrıntılı bilgi için Swagger.io Swashbuckle ile ilgili güncel ve daha ayrıntılı bilgileri bu linkten takip edebilirsiniz.

Asp.Net Core Distributed Cache Nedir ? Redis İle Kullanımı

Daha önceki yazılarımızda Asp.Net Core da in-memory cache nedir nasıl kullanılır konularına değinmiştik. Bu yazımızda ise asp.net core projelerinde distributed cache nasıl uygulanır inceleyeceğiz.

Distributed Cache

Distributed cache projelerimizde daha performanslı ve ölçeklenebilir (scalability) modüller geliştirebilmemize olanak sağlar. In-Memory cache'de o an uygulamanın çalışmakta olduğu server'ı cache storage olarak kullandığımızdan birden fazla server'da çalışan uygulamalar için bu cache'in dağıtık olarak bütün sunucularda bulunan uygulamalara paylaştırılması ve yönetilmesi gerekmektedir. Distributed cache'de veriler merkezi olarak store edilir ve böylelikle sunuculardan herhangi biri down olduğunda bile diğer sunucularda bulunan uygulamalar cache'de bulunan data'yı kullanabilmektedirler. Ayrıca cache yapısını bozmadan istediğiniz kadar yeni app-server eklediğinizde veya stop ettiğinizde cache bundan etkilenmeyecektir. 

1-) İlk adım olarak Makinamızda redis-server kurulu olması gerekmektedir. Kurulum ile ilgili şu yazıdan yararlanabilirsiniz ve localhost:6379'dan bağlanacağımız varsayalım.

Örnek proje

Redis kurduktan sonra örnek proje üzerinden ilerleyelim. İlk olarak vs'da bir asp.net core web api uygulaması oluşturalım. 

Asp.Net Core uygulamalarında distributed-cache özelliğini kullanabilmek için Microsoft.Extensions.Caching nasmespace'i altında bulunan ve nuget'ten de kurabildiğimiz IDistributedCache interface'i bulunmaktadır ve bu interface içerisinde cache CRUD işlemlerini senkron-asenkron şekilde yapabilmemizi sağlayan metotlar bulunmaktadır.

  public interface IDistributedCache
  {
    byte[] Get(string key);
    Task<byte[]> GetAsync(string key, CancellationToken token = default (CancellationToken));
    void Set(string key, byte[] value, DistributedCacheEntryOptions options);
    Task SetAsync(string key, byte[] value, DistributedCacheEntryOptions options, CancellationToken token = default (CancellationToken));
    void Refresh(string key);
    Task RefreshAsync(string key, CancellationToken token = default (CancellationToken));
    void Remove(string key);
    Task RemoveAsync(string key, CancellationToken token = default (CancellationToken));
  }

2-) İkinci adım olarak Startup.cs içerisinde bulunan ConfigureServices metodu içerisinde uygulamamız servislerine redis-distributed-cache'i configure edip eklememiz gerekmekte.

 public void ConfigureServices(IServiceCollection services)
 {
     services.AddDistributedRedisCache(option =>
     {
         option.Configuration = "localhost:6379";
     });
 }

3-) Üçüncü ve son adım ise IDistributedCache interface'ini kullanarak cache crud işlemlerini yapmak. Bunun için asp.net core web api projelerinde default olarak gelen ValuesController'ı kullanalım.

[Route("api/[controller]")]
public class ValuesController : Controller
{
    private readonly IDistributedCache _distributedCache;

    public ValuesController(IDistributedCache distributedCache)
    {
        _distributedCache = distributedCache;
    }

    // GET api/values
    [HttpGet]
    public async Task<string> Get()
    {
        const string cacheKey = "values";

        var cachedItem = await _distributedCache.GetStringAsync(cacheKey);
        if (!string.IsNullOrEmpty(cachedItem))
        {
            return cachedItem; 
        }
        else
        {
            const string str = "value1 value2 value3 value4 etc.";
            await _distributedCache.SetStringAsync(cacheKey, str);
            return str;
        }
    }
}

Yukarıda görüldüğü üzre Get metoduna gelen istekte ilk olarak ilgili key'e ait cache'de bir değer var mı kontrol edilir varsa cache'de bulunan değer return edilir yoksa ilgili storage'a (database etc.) gidilir return value alınır önce cache'e atılır sonrasında return edilir.

Asp.Net Core uygulamalarında distributed-cache konfigurasyonu ve kullanımı bu kadar basitti diyebiliriz. Redis gibi couchbase veya sql server kullanarak da asp.net core uygulamalarında distributed cache özelliğini kazandırabilirsiniz ve IDistributedCache interface'ini kullanarak basitçe cache crud işlemlerini yönetebilirsiniz.