NodeJS Projesine Swagger Entegrasyonu

Dökümantasyon Nedir? Dökümantasyonun Önemi

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 Nedir?

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 Swagger Generator kurulumu

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 arayüzümüze ulaşmak 

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’ların tanımı ve oluşturulması 

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 (tüm öğrenciler) 

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. 

Swagger ile get isteği (id ile tek öğrenci)

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

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 

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 

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.