İçindekiler
Bir uygulama yazarken, takımlararası iletişimi sağlamak, uygulamanın ne olduğunu ve hangi api isteklerini barındırdığını anlamak için kod okumaya çalışırsak, bazen büyük yapılar için bu içinden çıkılamaz bir hal alabilir. Burada anahtar nokta, bir dökümantasyona sahip olmak. Dökümantasyonu yazılan kodun kullanım kılavuzu olarak düşünebiliriz. Yazılım üretimi yapan çoğu kişi veya kurum dökümantasyon kullanımını atlayabiliyor, ve bu yazılımın düzgün ve hızlı bir şekilde devam edebilmesini ya zorlaştırır ya da yavaşlatır. Swagger kullanmak bize web çatısı altında bir dökümantasyon sağlar ve bu dökümantasyonu kullanarak, yazılan api route’larına kolayca erişebilir, bu route’lara istek atarak bize dönen data’ların ne olduğuna kolayca bakabilir ve anlayabiliriz.
Swagger API’ları görselleştirmeye ve yazılan servisleri test etmeye yarayan bir arayüz’dür. API methodlarının üstüne, yorum satıları ekleyerek, bu route’ları görsel bir şekilde web üzerinde doküman olarak görmemizi sağlayan ve bunlara istek atmamıza olanak sağlayan bir web arayüz aracıdır. XML ve JSON olarak kullanım sağlamamıza olanak tanır. XML Soap yapısı JSON ise REST yapısı kullanır.Günümüzde npm paketleri kullanmak işlerimizi kolaylaştıracağı için, biz de basitliğinden dolayı bir NodeJs npm paketi olan `express-swagger-generator` kullanacağız.
Express projemizin içinde,terminalimize `npm install express-swagger-generator` komutunu girip bir swagger paketi kurarak başlıyoruz.
Daha sonra kurduğumuz paketi projemizin içine dahil ediyoruz.
`const app = express();`
`const expressSwagger = require('express-swagger-generator')(app);`
Burada önemli nokta, Swagger paketimizi app’in altında çağırıp, daha sonra parantez içinde (app) parametresini vermek.
const app = express();
const expressSwagger = require('express-swagger-generator')(app);
Daha sonra options’ını ayarlıyoruz.
Yukarıda options verirken dikkat edilmesi gereken başlıca iki şey var. Birincisi, Base Path’i düzgün vermek, benim api’larımın base’inde bir şey olmadığı için sadece home “/” directory’sini verdim. İkincisi, “app.js” dosyamın içindeki Swagger satırlarından bir dökümantasyon oluşturmak istediğim için, files dizimin içine, “./app.js” dosyamın yolunu veriyorum.
Web üzerinden, Swagger ekranına ulaşmak için, gitmemiz gereken adres: “localhost:5000/api-docs”. Eğer host adresini options’a farklı bir şekilde tanımladıysak, o host üzerinden ulaşmamız gerekiyor. Biz options’da 5000 verdiğimiz için, o adress ile erişiyoruz.
Döküman ekranımızın web üzerindeki son arayüz hali şu şekilde olacak.
Swagger komutlarımızı çoklu yorum satırı açarak, route işlemlerimizin (get,post,put,delete) hemen üstüne yazıyoruz. Ve bu bize projemizi yaparken, bir taraftan da api dökümantasyon’u oluşturmamıza olanak sağlıyor
Swagger ile get isteği atarken, ilk olarak @swagger diyerek,swagger tanımlamamızı yapıyoruz. Sonraki satırda, isteğimizin hangi tip olduğunu büyük harfle belirleyip (GET,POST,PUT,DELETE), isteği atacağımız route’umuzu belirliyoruz.
Sonraki satırda, isteklerimiz Students model’imize bağlı olduğu için, tüm istekleri Students çatısı altında toplamak için bir @group oluşturup, açıklamamızı giriyoruz. Ve @summary ile isteğimizin ne yaptığını tam olarak özetliyoruz.
@returns kullanarak bize, başarı ve hata anında dönecek mesajları belirterek, Swagger’ımızı bu şekilde sonlandırıyoruz.
Yukarıda tek bir öğrenci getirmek için get isteği attığımız swagger’ın tek farkı ise, bir “id” parametresi alması. Ve bunu @param {string} id.path.required diyerek parametre almayı zorunlu hale getiriyoruz. Ve artık parametre vererek tek bir student alabiliyoruz. Bunu aşağıdaki adresste de görebiliriz.
Swagger ile post isteği atarken, ilk önce @typedef diyerek modelimizin adını tanımlıyoruz. Daha sonra, json body’de property olarak ekleyeceğimiz yerleri ve type’ları @propert {string} yazarak belirliyoruz, ve bunları zorunlu yapmak için required yapıyoruz.
Daha sonraki satırda @swagger tanımı yapıp, Student’imizi tekrar @typedef olarak tanımlıyoruz. Altına route ve açıklama yazılarımızı belirttikten sonra, post body’mizi @param {Student.model} ve Model’imizin body’sini zorunlu tutmak için required vererek tanımımızı yapıyoruz. Ve @returns kullanarak bize, başarı ve hata anında dönecek mesajları belirterek, swaggerımızı bu şekilde sonlandırıyoruz.
Swagger ile put isteği atarken, dikkat etmemiz gereken iki şey var, birincisi parametre olarak değiştireceğimiz kullanıcının id’sini almak, ikincisi ise değiştireceğimiz isteğin body’sini tanımlamak.
Body’de değişiklik yapacağımız için önce @typedef ile değişiklik yapacağımız model’i tanımlıyoruz ve @property decorator’ı ile body parametrelerini ve bunların type’ını tanımlıyoruz örneğin @property {string} name. Zorunlu olarak hepsini değiştirmeyeceğimiz için, required methodunu kullanmıyoruz.
Daha sonra ikinci bir swagger yorum satırı (/** */) açıyoruz.
Burada yine yukarıdaki route’larda yaptığımız işlemleri yapıyoruz ve decorator’ler tanımlıyoruz. @swagger tanımı yaparak, bunun bir swagger dökümantasyon işlemi olduğunu belirtiyoruz.Modelimizin type’ını @typedef Student olarak tanımlıyoruz. @route işlemi ile route tanımlayıp {id} ile sonuna parametre veriyoruz, çünkü modelin id’si ile işlem yapacağız.Güncelleyeceğimiz body zorunlu olduğu için bunu required yapıyoruz, error ve success mesajlarımızı return olarak döndükten sonra, swagger yorumlarımızı kapatıyoruz.
Swagger ile delete isteği atarken, dikkat edeceğimiz olay, silmek istediğimiz parametre’yi eklemek, bunu @param {string} id olarak yaptık, kullanıcı id’sini bularak silme işlemi yapmak istiyoruz. Bunun dışında yine @swagger ile bir swagger decorator’ı tanımlayıp, @route ile bir path ve atacağımız isteği tanımlıyoruz. Tüm istekleri tek bir Student group’unda toplamak için, @group parametresi veriyoruz. Route’un ne işe yaradığı hakkında bir özet için @summary parametresini kullanıyoruz. Ve son olarak, hata ve başarı mesajlarını dönerek kullanımımızı bitiriyoruz.
Yukarıdaki kodlara Github reposu içerisinden ulaşmak için bu bağlantıyı kullanabilirsiniz.
Yazılım Geliştiricisi
Uzaktan Çalışmayı Daha Verimli Hale Getirmek İçin İpuçları
Evden çalışmanın avantajları vardır, ancak kesinlikle dezavantajları da vardır. Motive olmak birçok insan için büyük bir zorluk olabilir,...
SAP Fiori Client Uygulama Mağazalarından Kaldırılıyor
SAP Fiori Client Uygulaması 2022’nin ikinci çeyreğinde Apple ve Google uygulama mağazalarından kaldırılacak. Peki bu gelişme Fiori kullanan...
Kimler e-İrsaliye Mükellefidir?
Dijital dönüşüm çözümleri arasında en çok tercih edilen uygulamalarından biri e-İrsaliye uygulamasıdır. Ticari faaliyetlerde bulunan...
SAP Signavio Process Collaboration Hub Nedir?
Günümüz iş dünyasında işletmelerin başarılı olması için iş birliği şarttır. Ancak, bu kadar çok farklı araç ve teknoloji...
e-Arşiv Fatura Sorgulama Nedir? Nasıl Gerçekleştirilir?
Dijital dönüşüme ister gönüllü ister zorunlu olarak geçmiş olun, alıcılarınız manuel yöntemleri kullanmakta ısrarcıysa süreciniz...
Elektronik Veri Değişimi (EDI) Kılavuzu
Günümüzde işletmeler, satın alma siparişlerini, faturalarını, teklif taleplerini, kredi uygulamalarını ve daha birçok belge türünü...
Üretim Süreçlerinizi İyileştiren 5 Yalın Teknik
Yalın üretim, işletmelerin iş süreçlerinde israfa neden olan faktörleri tespit ederek ortadan kaldırmasını, verimliliği ve kaliteyi...
ERP (Kurumsal Kaynak Planlama) Nedir?
ERP TanımıERP (Enterprise Resource Planning/ Kurumsal Kaynak Planlama) kuruluşların günlük iş faaliyetlerini yönetmeye yarayan bir yazılım...
E-Muhasebe Fişi Kılavuzunda Son Gelişmeler
Koronavirüs sebebiyle yaşadığımız pandemi döneminde, dijital dönüşüm çözümleri sayesinde muhasebe işlemlerinin büyük bir kısmının...
Mailiniz başarıyla gönderilmiştir en kısa sürede sizinle iletişime geçilecektir.
Mesajınız ulaştırılamadı! Lütfen daha sonra tekrar deneyin.