Swagger Nedir ve Kurulumu Nasıl Yapılır? - Webmaster Forum

Merhaba Ziyaretçi!
Kaydolmak için bir dakikanızı ayırın, aradığın şey kesinlikle burada ve %100 ÜCRETSİZ! Ne için bekliyorsun?
Hemen Üye Ol

Swagger Nedir ve Kurulumu Nasıl Yapılır?

Acemi Webmaster & Yeni Başlayanlar


Cevapla Yeni Konu Aç
 
LinkBack Seçenekler Stil
  #1  
Alt 06 Eylül 2022, 06:47:18
AboveShaft - ait Kullanıcı Resmi (Avatar)
Yönetici
 
İstanbul Şubesi
Üyelik Tarihi: 26 Kasım 2006
Mesajlar: 58.714
Konular: 31464
Aldığı Beğeni: 0
Verdiği Beğeni: 0
Standart Swagger Nedir ve Kurulumu Nasıl Yapılır?

Swagger Nedir?

Web API geliştirme aşamasında en elzem gereksinimlerden biri dokumantasyon gereksinimi olarak ifade edilebilir. Cunku API yontemlerinin ne işe yaradığı ya da ne şekilde kullanıldığı dokumantasyon sınırları icerisinde anlaşılır olması lazım. Api dokumantasyonunu elle yazmak ise hem zor hem de bu dokumantasyonu guncel bir şekilde tutmak icin son derece zor. Bir şekilde bu dokumantasyonun guncelliğinin korunması ve uretimin devamı gerekiyor. İşte tam da bu noktada swagger bir kurtarıcı gibi koşuyor ve sorunlu olan duruma bir cozum ışığı oluyor. Swagger ’ın başka bir onemli bir amacı ise RestApiler icin bir ara yuz sağlaması. Bu sayede insanların ve bilgisayarların kaynak koda ulaşma zorluğunu yaşamadan RestApilerin ozelliklerinin gozukmesinin incelemesinin ve anlaşılmasının koşulları sağlanmış oluyor.


Swagger ’ın Proje Eklenme Durumu
Genişletmek icin tıkla ...


Swagger ’ın Gradle icin projeye dahil edilebilmesi amacıyla build.gradle dosyası konumuna dependency olacak şekilde eklenmesi gerekiyor. Ayrıca Swagger ’ın Maven da projeye katılabilmesi amacıyla ise pom.xml dosyası konumuna yeniden dependency olarak eklenmesi son derece onemli.


Swagger ’ın Konfigurasyon İşlemi
Genişletmek icin tıkla ...


Swagger ’ın projeye dahil edildikten sonra bazı konfigurasyon işlemlerinin gercekleştirilmesi gerekiyor. @[Sadece kayıtlı ve aktif kullanıcılar bağlantıları görebilir. ]figuration olduğunun belirtilmesinden sonra @[Sadece kayıtlı ve aktif kullanıcılar bağlantıları görebilir. ]bleSwagger2 aracılığıyla Swagger 2.0 spesifikasyonu aktif duruma getiriliyor. DocumentationType.SWAGGER_2 ile Swagger 2 kullanılacağı belirtiliyor burayı 1.2 veya WEB ile değiştirmek mumkun select() ile de ApiSelectorBuilder instance ’sin dondurulme işlemi yapılıyor ve ayarlar bu işlemden sonra yapılıyor, apis() ile dokumana katılacak olan paketler secilebiliyor, şu an icerisinde butun paketler dahil olmak uzere isteğe bağlı olarak bunu değiştirerek belirlenen paketlerin kullanımı olağan, paths() ise bu durumlara benziyor. Yine aynı tarzda dokumana katılma durumu adreslerin belirlendiği konumda bulunuyor. Son aşamada yapılan proje olgunlaşmış oluyor }/swagger-ui.html adresine gidilerek swagger aracılığıyla meydana getirilmiş olan dokumantasyona ulaşabiliyor. Bu işlemlerin olası yanlışlığında işlemler başarısız oluyor ve bu işlemleri doğru bir şekilde yapmak gerekiyor. Bu yuzden zaman kaybı da yaşamamak icin işlemlerin yapılışının dikkatli bir şekilde surdurulmesi son derece onem arz ediyor.


API Dokumantasyon Onemi ve Swagger
Genişletmek icin tıkla ...


API ’ler kullanılmak amacıyla (consume) tasarlandığı icin tuketicilerin API ’nizi hızlı bir bicimde uygulayabilmesini ve anlaşılmasını sağlamak son derece onemli bir nokta. Bu nedenle ki api dokumantasyonu olmazsa olmaz bir konumda bulunuyor. Dokumantasyon hazırlamak da coğu insana gore bir işkence gibi geliyor. Ek olarak duşunelim ki zoru zoruna bir dokuman oluşturuldu guncelliğini koruyup okunabilirliğini muhafaza etmek de aynı derece zor.


Tuketici konumunda yer alan bir insan dokumana baktığı zaman “Tanımı nedir, bu servis ne iş yapar, icerisinde ne tur operasyonları barındırıyor, bu operasyonların kullanım bicimi hangi tarzda olmalı, giriş cıkış parametreleri hangi turde?” benzeri soruların kolay bir şekilde cevaplanması akıllarda şuphe bırakmaması gerekiyor. Rest API uygulamaları yazılırken kac tane endpointine bağlı olduğu, hangi endpointin gorev konumu hangi endpointe nasıl istek atılacağını belirlemek amacıyla geleneksel usul olarak her şeyi otomatik olarak değil elle yazarak bir dokumantasyon oluşturulmalı.


Bu şekilde API'yi kullanalar hangi iş icin neyi nasıl kullandığını kullanacağını oğrensin ve kavrasın. Eğer geleneksel usul takip edilmek istenmiyorsa biraz daha otomatik tarzda, yani biraz daha basit ve cok yonlu bir dokumantasyon yapılmak istenirse ortaya başka bir swagger cıkıyor. Bu başka olarak nitelendirilen swagger sadece dokumantasyon amacıyla kullanılmıyor. Rest API client kodununda uretimi yapılıyor. Oradan hareketle direkt istek gonderilip sonuclara ulaşılabiliyor. Postman tarzı bir uygulama kullanılmadan da yapılan iş cozume kavuşabiliyor.


Swagger Kurulumu
Genişletmek icin tıkla ...


Ornek olacak Projeye swagger eklemek amacıyla ilk olarak open source olarak geliştirilen Swashbuckle ismindeki kutuphaneyi proje sınırları dahilinde Nuget Package Manager Console kullanarak indirip kurma işlemi yapılacak. Kurulum işlemleri sonra erdikten sonra solution icerisinde yer alan ve App_Start klasoru acılarak bunun icerisine swagger configuration işlemleri yapmak amacıyla SwaggerConfig.cs isminde bir class eklendiği goruluyor. SwaggerConfig.cs icerisi default olarak aşağıda yer aldığı gibi gozukebilir.

Proje run edildiği zaman browser vasıtasıyla Swagger Ui sayfasına doğru /swagger tarzında ulaşılabilir ve sayfa default olarak da aşağıda yer aldığı gibi gozukuyor.

Yukarıda da yer aldığı gibi gibi projede controller'lar sınırları dahilinde tanımlı olarak yer alan end-point'ler, Http Request ceşitleri, almış oldukları parametreler vs benzeri bilgiler de yer alıyor. Ornek vermek gerekirse POST /api/Values metodu bu noktada ornek olarak verilebilir. Metot adının uzerine tıklandığı zaman alt kısımda bir view expand oluyor ve bu noktada request olacak şekilde gonderilecek olan parametreler yazılıp response olarak alınabiliyor.


Yukarıda yer alan ekran goruntusunde bulunan kısaca Values metodu string tarzda bir parametre alıyor. Sonrasında da geriye string bir response olarak donuyor. Request parametresi yazıldıktan hemen sonra Try it out butonuna tıklandığı zaman da aşağıda yer alan bir ekran ile karşılaşmak son derece mumkun. Bu mumkun olan durum aşağıda gorulduğu uzere gorsel olarak incelenebilir.


Bu durumdan yararlanan ve bu duruma kafa yoran yazılımcılar icin sıkıntı haline gelen request response ornek kodları ifade etme dokuman vs benzeri konuları da swagger vasıtasıyla bilhassa kolay ve cok yonlu bir hale getirmek mumkun. Swagger ile alakalı da daha birden cok configuration bulunuyor. VS uzerinden XML dosya generate edilerek kodların ustunde yer alan yorumlar izleyip yol edinip api dokumanı oluşturmak gibi birden cok mahareti bulunuyor. Detaylı bilgi icin de Swagger.io Swashbuckle ile alakalı guncel ve daha detaylı bilgiler icin hep bir takipte bulunmak son derece onemli. Yukarıda kolay tarzıyla swagger anlatıldı fakat en başta da belirtildiği gibi swagger.config dosyasını duzgun yorumlayabilme becerisini kazandıktan sonra daha bircok ozellik bu vasıtayla bulunabilir.


Ozetleyecek Olursak :
Genişletmek icin tıkla ...


Swagger yazılımlar icin cokca kullanılan ve bu uğurda bir bilgi birikimi gerektiren bir konumda bulunuyor. Web API değiştirip geliştirme noktasında yer alan en onemli ihtiyaclardan biri dokumantasyon gereksinimi olacak şekilde acıklanıyor olmasının en buyuk sebebi de oneminden kaynaklanıyor. Projeye dahil edilen swaggerin bazı konfigurasyon işlemlerinin yapılmasının gercekleştirilmesi son derece beklenen ve onemsenen bir durum. Bu yuzden bu adımlar dikkatli bir şekilde doğruca uygulanıp kavranmalı. Swagger.config dosyasının doğru bir şekilde değerlendirilip doğru cıkarımının yapıldığı zaman bu becerinin aracılığıyla bircok ozellikten ve katkıdan yararlanılabileceğin bilinmesi onemli.

Cevapla Yeni Konu Aç


Konuyu toplam 1 üye okuyor. (0 Kayıtlı üye ve 1 Misafir)
 
Seçenekler
Stil

Yetkileriniz
Sizin Yeni Konu Acma Yetkiniz var yok
You may not post replies
You may not post attachments
You may not edit your posts

BB code is Açık
Smileler Açık
[IMG] Kodları Açık
HTML-KodlarıKapalı
Trackbacks are Açık
Pingbacks are Açık
Refbacks are Açık


Şu Anki Saat: 00:32:31
İletişim