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

რეალურ სამყაროში უმეტესწილად პროექტის 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 - იხილეთ სვაგერის დოკუმენტაცია

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

როგორ ჩავაინტეგრიროთ სვაგერი ლარაველში?

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

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

npm install swagger-ui

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

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

openapi: 3.0.0
info:
  title: Coronatime API
  description: Here goes description
  version: 0.1.9

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

paths:
  /users:
    get:
      summary: Returns a list of users.
      responses:
        '200': 
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

ახლა კი resources/js -ში შევქმნათ სვაგერისთვის ჯავასკრიპტის ფაილი, რომელიც დაამუშავებს api.yaml-ს და დააგენერირებს სვაგერის ინტერფეისს:

სვაგერის swagger.js ფაილში შემდეგი ჯავასკრიპტის სნიპეტი ჩავსვათ:

import SwaggerUI from 'swagger-ui'
import 'swagger-ui/dist/swagger-ui.css';

SwaggerUI({
    dom_id: '#swagger-api',
    url: '/api.yaml',
});

ეს სნიპეტი დააგენერირებს სვაგერის ინტერფეისს და შესაბამის html-ს იმ ტეგის ქვეშ ჩასვამს, რომლის id-იც არის swagger-api.

ახლა საჭიროა, რომ webpack.mix.js-ში მივუთითოთ mix-ს რომ ჩვენი swagger.js გადააკმპილიროს public/js საქაღალდეში ბრაუზერისათვის წაკითხვად ჯავასკრიპტის ფაილად, რომ შემდეგ ჩვენს ბლეიდში გამოვიყენოთ ეს ჯავასკრიპტის ფაილი: თუ ჩვენი პროექტი ლარაველის ისეთ ვერსიაზეა შექმნილი რომელიც ბანდლეარ vite-ს იყენებს უნდა ჩავსვათ vite.config.js-ში webpack.mix.js-ის ნაცვლად. (იხ. სურათი 1.2)

1.1

1.2

გავუშვათ npm run dev და დავინახავთ, რომ public/js საქაღალდეში უკვე გვაქვს swagger.js-ის საბოლოო ფაილი. public/build/assets/

ახლა შევქმნათ Blade ფაილი სვაგერის ინტერფეისის გვერდის დასარენდერებლად სადაც გვექნება ერთი div, რომელსაც id ექნება swagger-api და ასევე ჩავსვათ ჩვენი სვაგერის სკრიპტი(vite-ის შემთხვევაში სურათი 1.4): ასევე vite-ს შემთხვევაში გაშვებული უნდა გვქონდეს npm run dev

1.3

1.4

ახლა კი შევქმნათ ერთი მარშრუტი საიდანაც ჩვენს Swagger-ის ბლეიდს დავარენდერებთ:

ახლა კი ვესტუმროთ ჩვენს მარშრუტს და Magic:

⚠️ ამ შემთხვევაში სვაგერის მარშრუტი ყველასათვის ხელმისაწვდომია. რეალურ პროექტში საჭირო იქნება რაიმე middleware-ში მოექცეს ზემოხსენებული მარშრუტი, რომ მხოლოდ ავტორიზებულ მომხმარებელს ქონდეს წვდომა სვაგერში არსებული ინფორმაციაზე.

⚠️ ასევე რეალურ პროექტში api.yaml-იც ასე ყველასათვის ხელმისაწვდომად არ უნდა იყოს public საქაღალდეში მოქცეული.

Security

როგორც წესი არ გვინდა რომ ჩვენი API დოკუმენტაცია ყველასთვის საჯაროდ იყოს ხელმისაწვდომი. რის გამოც საჭიროა, რომ პროდაქშენზე დავბლოკოთ წვდომა შესაბამის როუტსა და ფაილებზე.

იმისათვის რომ პროდაქშენზე უცხო ადამიანი პირდპაირ არ მისწვდეს ჩვენს .yaml-ის ფაილებს საჭიროა nginx კონფიგურაციაში ჩავამატოთ შემდეგი კოდი

server {
 ..... სხვა კონფიგურაციები

 location = /api.yaml {
     deny all;
     return 403;
 }

# [!] იმ შემთხვევაში თუ api.yaml ის გარდა სხვა ფაილებად არის დაყოფილი კი ეს კოდი
# [!] ყურადღება მიაქციეთ ფოლდერის სახელს, თუ დამატებითი ფაილები არ არის მოთავსებული 
# [!] _swagger დირექტორიაში, მის ნაცვლდა მიუთითეთ სასურველი დირექტორიის სახელი.
 location ~ /_swagger/.* {
     deny all;
     return 403;
 }

 ..... სხვა კონფიგურაციები
}

ასევე შევზღუდოთ წვდომა შესაბამის როუტზე web.php ფაილში

<?php

use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Route;

/*
|--------------------------------------------------------------------------
| Web Routes
|--------------------------------------------------------------------------
|
| Here is where you can register web routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| contains the "web" middleware group. Now create something great!
|
*/

Route::get('/swagger', fn () => App::isProduction() ? response(status:403) : view('swagger'))->name('swagger');