API-ის დოკუმენტაცია, Swagger-ის ინტეგრაცია Node.JS-ში

რეალურ სამყაროში უმეტესწილად პროექტის Front-End და Back-End არის განცალკაევებული და Front-სა და Back-ს შორის კომუნიკაცია Rest API-ების მეშვეობით ხდება.

ოდნავ მოზრდილ პროექტში Back-ის API სერვისების რაოდენობამ შეიძლება 50-საც კი გადააჭარბოს. შესაბამისად Front-End დეველოპერსა და Back-End დეველოპერს შორის თითოეულ ამ სერვისზე კომუნიკაცია უბრალო მიმოწერით, საუბრით და ა.შ. საკმაოდ არაეფექტურია და პროექტის მსვლელობისას ბევრ ცდომილებას, ხარვეზს და უსიამოვნო შემთხვევებს იწვევს.

ზუსტად ამ პრობლემას აგვარებს ხელსაწყო Swagger.

სვაგერი მოკლედ, რომ ვთქვათ არის ჩვენი API-ების Readme ფაილი. ოღონდ სვაგერის Readme-ის მარქდაუნის ნაცვლად YAML-ით ვწერთ.

აღვწერთ თითოეულ ჩვენს API-ის შემდეგი თვისობრიობის მიხედვით:

• რა url-ზე უნდა მივაკითხოთ? ( /users )

• რა მეთოდის API-ია? (GET, POST, PUT,... DELETE)

• რა მარშრუტის პარამეტრები აქვს? (Query Params)

• რა Body-ის პარამეტრები აქვს

• როგორ პასუხუს უნდა ველოდოთ? რა სტატუს კოდით?

ამ და სხვა ინფორმაციას რაც საჭიროა, რომ Front-End და Back-End დეველოპერს შორის გაზიარდეს აღვწერთ ჩვენს სვაგერის დოკუმენტაციაში YAML ფაილის მეშვეობით.

მეტი ინფორმაციისთვის თუ როგორ უნდა აღვწეროთ API - იხილეთ სვაგერის დოკუმენტაცია

ამასთანავე, სვაგერის ინტერფეისი საშუალებას გვაძლევს თითოეულ ამ სერვისზე რექვესთი გავგზავნოთ და მივიღოთ პასუხი, რაც არანორმალურად მნიშვნელოვანია სერვისების გასატესტად და გასაცნობად.

როგორ ჩავაინტეგრიროთ სვაგერი Node.JS-ში Express-თან ერთად?

არსებობს swagger-ui-express ბიბლიოთეკა, რომელსაც შეუძლია yamljs ბიბლიოთეკასთან ერთად yaml-ის ფაილი შესაბამის სვაგერის ინტერფეისად დაარენდეროს.

დავაინსტალიროთ ჩვენს ლარაველის პროექტში swagger-ui-express და yamljs ბიბლიოთეკები შემდეგი ბრძანებით:

npm install swagger-ui-express yamljs

შემდგომ config საქაღალდეში შევქმნათ swagger.yaml ფაილი:

შემდგომ swagger.yaml-ში ჩავსვათ პატარა სვაგერის სნიპეტი, რომლის საშუალებითაც დავაგენერირებთ სვაგერის ინტერფეისს:

openapi: 3.0.0
info:
  title: NodeJS Project
  description: Here goes description
  version: 0.1.9

servers:
  - url: http://localhost:4444/api
    description: local server
  - url: http://producation.app/api
    description: production server

paths:
  /users:
    get:
      responses:
        '200': 
          description: Returns a list of users.
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: object
                  properties:
                    firstName: 
                      type: string
                    lastName: 
                      type: string
                    email:
                      type: string
                  example:
                    firstName: gela
                    lastName: iashvili
                    email: [e-mail]

ახლა კი შევქმნათ server.js ფაილი პროექტის ძირეულ საქაღალდეში:

const express = require('express')
const Router = require('express').Router
const {faker} = require('@faker-js/faker')
const YAML = require('yamljs')
const swaggerUI = require('swagger-ui-express')

/**
 * Load swagger document.
 */
const swaggerDocument = YAML.load('./config/swagger.yaml')

/**
 * Create Express server.
 */
const server = express()

/**
 * Setting up swagger middleware.
 */
server.use('/api-docs', swaggerUI.serve, swaggerUI.setup(swaggerDocument))


/**
 * Create Express Router.
 */
const router = Router()

/**
 * Create route which generates random users.
 */
router.get('/api/users', (_, res) => {
    let usersCount = faker.random.numeric(2)

    const users = []

    while(usersCount--)
    {
        users.push(
            {
                name: faker.name.firstName(),
                email: faker.internet.email(),
                image: faker.internet.avatar(),
            }
        )
    }
    

    res.json(users)
});

/**
 * Register express router.
 */
server.use(router)

/**
 * Listen for incoming connection.
 */
server.listen(4444, () => console.log('Server started at http://localhost:4444'))

იმისათვის, რომ პროექტი გავუშვათ, საჭიროა დავაინსტალიროთ შემდეგი ბიბლიოთეკები:

• express

• @faker-js/faker

• swagger-ui-express

• yamljs

გავუშვათ express-ის სერვერი ბრძანებით:

node server.js

და ვესტუმროთ url-ს http://localhost:4444/api-docs სადაც რეალურად დავინახავთ სვაგერის ინტერფეისს:

რეალურად სვაგერის ინტერფეისის გენერაციისათვის საქმეს აკეთებს შემდეგი კოდი:

const express = require('express')
const Router = require('express').Router
const YAML = require('yamljs')
const swaggerUI = require('swagger-ui-express')

/**
 * Loaded swagger document.
 */
const swaggerDocument = YAML.load('./config/swagger.yaml')

/**
 * Express server
 */
const server = express()

/**
 * Setting up swagger middleware.
 */
server.use('/api-docs', swaggerUI.serve, swaggerUI.setup(swaggerDocument))

განვიხილოთ რა ხდება:

• პირველ რიგში გვაქვს დაიმპორტებული express, express-ის როუტერი, YAML ფაილის პარსერი და Swager-ის ინტერფეისის გენერატორი

• მე-9 ხაზზე swaggerDocument-ში ვინახავთ გაპარსულ swagger.yaml ფაილს

• 14-ე ხაზზე ექსპრესის სერვერს ვქმნით

• ხოლო 19 ხაზზე კი კონკრეტულ მარშრუტს('/api-docs') ვანიჭებთ სვაგერის middleware-ებს

ეგ არის 👏

იმ შემთხვევაში, თუ VSCode-ს ვიყენებთ რეკომენდირებულია OpenAPI-ის ექსთენშენის დაყენება, რომელიც Swagger-ის დოკუმენტაციის წერისას autocomplete-ს გაააქტიურებს