# 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 - იხილეთ სვაგერის დოკუმენტაცია](https://swagger.io/docs/specification/about/)

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

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

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

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

```
npm install swagger-ui-express yamljs
```

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

![](/files/RiEfftNMCBkwhKZGGp0K)

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

```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: gela@redberry.ge
```

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

```javascript
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'))
```

{% hint style="info" %}
იმისათვის, რომ პროექტი გავუშვათ, საჭიროა დავაინსტალიროთ შემდეგი ბიბლიოთეკები:

* express
* @faker-js/faker
* swagger-ui-express
* yamljs
  {% endhint %}

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

```
node server.js
```

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

![](/files/9Jdy49VpJVHw3xhd5kau)

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

```javascript
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-ებს

ეგ არის :clap:

{% hint style="info" %}
იმ შემთხვევაში, თუ VSCode-ს ვიყენებთ რეკომენდირებულია [OpenAPI](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi)-ის ექსთენშენის დაყენება, რომელიც Swagger-ის დოკუმენტაციის წერისას autocomplete-ს გაააქტიურებს
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://redberry.gitbook.io/resources/node-js/api-is-dokumentatsia-swagger-is-integratsia-node.js-shi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.