Derinlemesine yazılım eğitimleri için kanalımı takip edebilirsiniz...

Asp.NET Core – Swagger Aracı

Yazar: Gençay · Yayımlanmış 06 Mayıs 2019 · Güncellendi 06 Mayıs 2019

Merhaba,

Bu içeriğimizde Restful servisler için olmazsa olmaz bir döküman aracı olan Swagger’i inceliyor olacağız. Swagger; web API uygulamalarında endpointleri test etmek yahut server side uygulamalarına entegre olacak clientlara yardımcı olmak için uygulamadaki tüm endpointleri otomatik analiz edebilen ve bunların testi için hali hazırda bir arayüz oluşturan developer dostu bir araçtır. Hemen hemen her modern programlama dili ve ortamında Swagger desteklenmektedir.

Swagger, sistemdeki tüm endpointleri yakalayabilmek için tüm controller’lar ve içlerindeki actionları bir .json formatındaki veri ile tutmakta ve bunu dökümantasyon için kullanılan Swagger-UI işlevsel arayüzüne göndermektedir. Böylece gelişim sürecindeki API uygulamasında değişen yahut yeni eklenen tüm endpointler Swagger aracı sayesinde dinamik olarak yakalanabilmekte ve bu durumda bizler açısından total maliyetten oldukça kâr elde edilmektedir. Dolayısıyla sürekli gelişen yahut değişen bir sistemi dökümante şekilde tarif edebilmek sürekli takip ve döküman güncellemesi gerektireceğinden dolayı oldukça yoğun bir emek sarf etmemizi gerektirecektir.

İşte Swagger, tüm bu emekleri doğru yere sarf etmemiz ve enerjimizi doğru yere yönlendirmemiz için geliştirilmiş bir yapılanmadır. Tüm bunların yanında dökümante özelliğiyle birlikte endpointleri sunmuş olduğu Swagger-UI üzerinden hızlıca test etmemizi sağlayarak taktirleri katbekat hak etmeyi başarmıştır.

Kurulumu

Swagger aracını kullanabilmek için ilk olarak için şu adresteki en güncel sürümünü istediğiniz yöntemle uygulamaya indiriniz. Örnek olarak bu içeriğin klavyeye alındığı anda en güncel olarak bulunan “4.0.1” sürümünü .NET CLI aracılığıyla aşağıdaki kod sayesinde uygulamaya import ediyorum.

dotnet add package Swashbuckle.AspNetCore --version 4.0.1

Swashbuckle isimli kütüphanenin Swagger için otomatik UI üretilmesini sağlayan bir sorumluluğu mevcuttur.

Entegrasyonu

Bu işlemden sonra Swagger aracını uygulamaya entegre etmek için Startup dosyasında “ConfigureServices” metodu içerisinde “AddSwaggerGen” metodunu aşağıdaki gibi kullanıyoruz.

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

Yukarıdaki kod bloğunu incelerseniz eğer uygulamaya Swagger kütüphanesi dahil edilmekte bununla beraber oluşturulacak Swagger dökümanının temel konfigürasyon ayarları sağlanmaktadır.

Bu işlemden sonra servis olarak eklenen Swagger aracını, uygulamanın kullanması için yine Startup dosyasındaki “Configure” metodu içerisinden aşağıdaki gibi ayarlamamız gerekmektedir.

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            .
            .
            .
            app.UseSwagger();
            app.UseSwaggerUI(_ => _.SwaggerEndpoint("/swagger/docname/swagger.json", "Project Name"));
            .
            .
            .
        }

Burada ise “UseSwagger” metodu ile uygulamanın Swagger aracını kullanmasını, “UseSwaggerUI” metodu ile ise kullanılacak Swagger aracının UI endpoint bilgilerini ayarlamış bulunmaktayız. Muhtemelen gözünüze ilişmiştir ama ben yinede ifade etmiş olayım ki, “SwaggerEndpoint” fonksiyonu içerisinde birinci olan “url” parametresi değer olarak yukarıda tanımlanmış olan Swagger dökümanının adını dizininde kullanmak zorundadır.

Artık bu işlemlerden sonra uygulamayı çalıştırıp https://localhost:****/swagger şeklinde bir istekte bulunursanız sizi Swagger ekranı karşılayacaktır.

İlgili ekran üzerinden aşağıdaki ekran görüntüsünde olduğu gibi uygulamadaki tüm endpointleri görebilir, onları deneyebilir, deneme sonucundaki verileri .json olarak elde edebilir ve bu şekilde yapılanmayı tam teferruatlı dökümante etmiş oluyoruz.