NodeJs Üzerinde Swagger Entegrasyonu

Selamlar,

Bu makale, bir önceki NodeJS, MongoDB ve Angular 8 ile Full Stack Proje Oluşturmak makalesinin devamıdır. Bu makalede, yazılmış bir NodeJs üzerinde swagger implementasyonu yapılacaktır. Swagger hakkında daha detaylı bilgiye, bu makaleden erişebilirsiniz.

Swagger UI Express : Kütüphanesi aşağıdaki komut ile indirilir. Böylece swagger dökümanın, Url’den çağrılması ile gösterimi sağlanır.

service.js: Var olan service.js dosyasına swagger eklentisi için aşağıdaki kodlar eklenir.

• “var swaggerUi = require(‘swagger-ui-express’)” : Swagger-UI-Express projeye dahil edilir.
• “swaggerDocument = require(‘./swagger.json’)” : Tanımlı NodeJs servislerinin dökümanı yani swagger dosyası, aynı local path altında swagger.json olarak tanımlanır.
• “app.use(‘/swagger’, swaggerUi.serve, swaggerUi.setup(swaggerDocument))” : Burada swagger için gerekli routing işlemi yapılmakta, ayrıca ilgili url’e gidildikten sonra örneğin bu örnekte “/swagger” gösterilecek “./swagger.json” dosyası tanımlanmaktadır.

Not : NodeJs üzerinde swagger dosyası, .Net Core’dan farklı olarak manuel olarak yaratılmalıdır. Bu da yeni bir method eklendiğinde ya da güncellendiğinde, var olan swagger document’inin de manuel olarak güncellenmesi anlamına gelmektedir.

Swagger.json dosyası oluşturulurken yapılan değişikliklerin, kaydetmeden ve proje derlenmeden kolaylıkla görülebilmesi için yukarıda görülen Swagger View extensiton’ı, VS Code üzerinde indirilir. İndirme işleminden sonra, aşağıda görüldüğü gibi swagger.json dökümanı sağ tıklanıp gerçek zamanlı örnek görünümü, sayfa üzerine getirilebilir. Swagger.json üzerinde yapılan tüm değişiklikler, bu view üzerinde anlık olarak gözükür.

swagger.json: Projenin bulunduğu ana folder üzerinde, swagger.json dosyası aşağıdaki gibi yaratılır. Önemli olan bazı methodların swagger karşılıkları açıklanmıştır.

• “swagger”: Güncel versiyon numarası tanımlanır.
• “info”: Swagger dökümanı üzerindeki açıklama, başlık ve lisans bilgileri burada tanımlanır.
• “tags” : Servisler çalıştıkları modelere göre guruplara ayrılırlar.
• “consumes, produces” : Servislerde çalışılacak format tipi tanımlanır.
• “paths” : Tüm servis methodlarının routing yani yolları ile tanımlandığı  alandır.
• “definitions” : Servis methodlarında kullanılacak tüm modeller bu alanda tanımlanır.
• Aşağıda görüldüğü gibi, bir önceki makalede yazdığımız tüm çalışanların çekildiği “/people” methodunun swagger karşılığı aşağıdaki gibidir.
  • “/people” : İlgili path bu şekilde belirtilir. Yani ilgili method bu şekilde çağrılır.
  • “get”: { “tags”: [ “Users” ] : get methodu olduğu ve swagger’da guruplama amaçlı kullanılan tag tanımlamasında “Users” etiketi altında konumlanan bir methoddur.
  • “summary”: “Get all users in system” : Methodun yapacağı işin anlatıldığı açıklama kısmı.
  • “responses” : Dönüş tipi ve mesajı burada tanımlanır.
  • "/people": { "get": { "tags": [ "Users" ], "summary": "Get all users in system", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/User" } } } } }

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

    "/people": {         "get": {           "tags": [             "Users"           ],           "summary": "Get all users in system",           "responses": {             "200": {               "description": "OK",               "schema": {                 "$ref": "#/definitions/User"               }             }           }         }       }

• Yukarıda görüldüğü gibi yeni bir çalışanı kayıt eden “/insertPeople” methodunun, swagger karşılığı aşağıdaki gibidir.
  • “/insertPeople” : methodun routing’i bu şekilde tanımlanır. Yani ilgili method bu şekilde çağrılmalıdır.
  • “post”: { “tags”: [ “Users” ] : “post” methodu olduğu ve gene “Users” tagının altında konumlandığı, bu şekilde tanımlanır.
  • “summary”: “Create a new user in system” : Methodun yapacağa işin tanımı “summary” node’u altında tanımlanır.
  • “parameters”: methodun aldığı parametreler, bu node altında tanımlanmıştır.
    • “name”: “model”: Adı model.
    • “in”: “body” : İlgili parametreler servise,
      • “Head” : Header’da gönderilen parametrelerdir,
      • “Body” : Bu örnekte olduğu gibi , servisde “req.body” şeklinde alınan “Json” formatında gönderilen parametrelerdir,
      • “Path” : Mvc Routing’de olduğu gibi “/X/Y” şeklinde tanımlanan parametrelerdir,
      • “Query” :”Url içinde “?” ile tanımlanan parametrelerin gönderim şeklidir. Örnek : “/getpeopleByLastname?lastname=kasmer”
    • “description” : Gönderilen parametrelerin açıklamasıdır.
    • “schema” : Eğer parametre olarak bir model dönülüyor ise, “schema” ile gönderilecek modelin tipi, sayfanın sonundaki “definitions” altındaki modellerde tanımlanır ==>””#/definitions/User””
  • “responses” : Servisden gelen cevaplar, tiplerine göre yapacakları işler, burada tanımlanır.
    • “200” : Başarılı olur ise yapılacak işlem, burada tanımlanır.
    • “400” Hatalı olur ise, yapılacak işlem burada tanımlanır.
  • "/insertPeople": { "post": { "tags": [ "Users" ], "summary": "Create a new user in system", "produces": [ "application/json" ], "parameters": [ { "name": "model", "in": "body", "description": "person detail", "required": true, "schema": { "$ref": "#/definitions/User" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/User" } }, "400": { "description": "Failed. Bad post data." } } } }

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

    "/insertPeople": {         "post": {           "tags": [             "Users"           ],           "summary": "Create a new user in system",           "produces": [             "application/json"           ],           "parameters": [             {               "name": "model",               "in": "body",               "description": "person detail",               "required": true,               "schema": {                 "$ref": "#/definitions/User"               }             }           ],           "responses": {             "200": {               "description": "OK",               "schema": {                 "$ref": "#/definitions/User"               }             },             "400": {               "description": "Failed. Bad post data."             }           }         }       }

• Yukarıda görüldüğü gibi çalışanları sayfalayarak getiren “/getpeoplebyPaging” methodunun, swagger karşılığı aşağıdaki gibidir.
  • “/getpeoplebyPaging/{page}/{count}”: Methodun routing tanımlamasında parametreler, tip olarak Path şeklinde gönderilmiştir.
  • “summary”: “Get user list by paging”: Methodun yaptığı iş, summary kısmında tanımlanmıştı.
  • “parameters”: Bu method’a gönderilen parametreler, burada tanımlanır. 2 parametre almaktadır. Page ve count.
    • { “name”: “page”, “in”: “path”, “required”: true, “description”: “Page number of person list”, “type”: “string” } : Parameter adı “name” ile, gönderilme şekli “in” ile, “required” zorunlu olup olmadığı, açıklaması “description” ile ve son olarak tipi “type” ile tanımlanır.
  • “responses” : Methodun dönüş tipleri, bu bölümde tanımlanır. “200” işlem başarılı olmuş ise. “404” : Servis bulunamamış ise gibi…

Yazılan swagger.json dosyalarında, bazen hatalar olabilir. Bunların düzeltilebilmesi için size kolaylık sağlayacak, https://editor.swagger.io online editörünü şiddet ile tavsiye ediyorum. Çünkü bazen hataların, manuel olarak bulunması gerçekten zor olabilmektedir. Ayrıca bu online editör ile swagger.json dosyası, istenen bir dosya tipine export edilebilmektedir. Hepsinden önemlisi, aşağıda görüldüğü gibi swagger.json dosyaları değerinde :) NodeJs, .Net Core gibi servislere dönüştürülebilmektedir.

swagger.json (Tümü) :  Manuel olarak hazırlanan swagger dökümanı aşağıdaki gibidir. Unutulmamalıdır ki yeni bir method eklendiğinde, güncellendiğinde ya da silindiğinde, bu dökümanın da güncellenmesi gerekmektedir.

Geldik bir makalenin daha sonuna. Bu makalede, bir web service’inde benim için olmazsa olmazlarından swagger’dan bahsettik. Swagger bir webservisi dokümanıdır. Tek farkı, canlı olarak  test edilebilmesidir. .Net Core’da swagger entegrasyonu çok basit bir şekilde yapılabilirken, NodeJs’de bu işlem biraz daha zahmetlidir. Ama harcanan her dakikaya değmektedir. Eğer bir ekip ile çalışıyor iseniz, ya da servislerinizi dışarı açıyorsanız, eğer projenizde swagger var ise kimse sizden ekstra bir döküman istemeyecektir. Ayrıca yapılan düm değişiklikler swagger üzerinden kolaylıkla takip edilebilecektir.

Yeni bir makalede görüşmek üzere hepinize hoşçakalın.

Soruce :

• https://blog.cloudboost.io/adding-swagger-to-existing-node-js-project-92a6624b855b
• https://www.npmjs.com/package/swagger-ui-express