İç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
SAP GRC Nedir?
SAP GRC TanımıAçılımı Governance, Risk ve Compiance olan GRC, kuruluşların risk, uyumluluk ve kurumsal yönetişim süreçlerini...
SAP ECC’den SAP S/4HANA’ya Geçiş Süreci
Kurumsal Kaynak Planlama (ERP) çözümleri işletmelerin temel operasyonlarını bir yazılım ile yönetmesini sağlamak için tasarlanmış...
SAPUI5’i Tanıyalım
SAPUI5, herhangi bir tarayıcı ile çalışan, Javascript, CSS ve HTML5 tabanlı bir UI (kullanıcı arayüzü) teknolojisidir. UI, kullanıcının...
Üretim Yönetim Sistemi Nedir?
Üretim Yönetim Sistemi (MES), kalite ve verimliliğin üretim sürecine dahil edilmesini ve sistematik olarak uygulanmasını sağlayan yazılım...
Elektrikli Şarj Hizmetlerinde Faturaların Oluşturulma Süreci
Gelir İdaresi Başkanlığı (GİB) tarafından Aralık 2023 tarihinde paylaşılan "Elektrik Şarj Hizmetlerine İlişkin Fatura Teknik Kılavuzu"...
NodeJS Projesine Swagger Entegrasyonu
Dökümantasyon Nedir? Dökümantasyonun ÖnemiBir uygulama yazarken, takımlararası iletişimi sağlamak, uygulamanın ne olduğunu ve hangi api...
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...
Sequelize ile Tablo İlişkileri Nasıl Yapılır?
Sequelize Nedir?Sequelize, NodeJs tabanlı bir ORM (Object-Relational Mapping) yazılımıdır. Veritabanı yapılarını Obje ve onun...
Banka Entegrasyonu Nedir?
İşletmelerden bireylere kadar herkes günden güne gelişen dijital dünyada yerini almaktadır. Teknoloji ile birlikte dijital dönüşümün bir...
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.