مستندسازی API در لاراول با سواگر: گامی مهم در مسیر توسعه حرفه ای

Swagger یک ابزار قدرتمند است که به توسعه‌دهندگان کمک می‌کند تا وب سرویس‌های RESTful خود را به راحتی مستند کنند. با استفاده از Swagger، می‌توانید مشخصات و توصیفات جامعی از وب سرویس‌های خود ایجاد کنید و به سادگی با سایر توسعه‌دهندگان و تیم‌ها در مورد این سرویس‌ها هماهنگ شوید. در این مقاله، به بررسی دقیق تعریف Swagger، مزایا و کاربردهای آن می‌پردازیم و نحوه استفاده از آن در لاراول را تشریح می‌کنیم.

1. Swagger چیست؟

Swagger یک فریمورک متن‌باز است که توسعه‌دهندگان را قادر می‌سازد تا مستندات جامعی از وب سرویس‌های RESTful خود ایجاد کنند. این ابزار با استفاده از یک رویکرد مبتنی بر نوشتار JSON یا YAML، امکان تعریف و توصیف وب سرویس‌ها را به صورت استاندارد و خودکار فراهم می‌کند.Swagger قابلیت اتصال به فریم‌ورک‌های مختلف را دارد. با استفاده از پلاگین‌ها و ابزارهای مرتبط، می‌توانید Swagger را به فریم‌ورک‌های محبوبی مانند Node.js, laravel، Python، Java و غیره متصل کنید.

2. مزایا و کاربردهای Swagger

Swagger باعث سهولت و شفافیت در توسعه و توسعه‌دهی وب سرویس‌ها می‌شود. برخی از مزایا و کاربردهای این ابزار عبارتند از:

ایجاد مستندات جامع و خودکار از وب سرویس‌ها
امکان استفاده توسط توسعه‌دهندگان و تیم‌های مختلف
هماهنگی آسان بین توسعه‌دهندگان و سایر اعضای تیم
افزایش روان‌نویسی کد با استفاده از توصیف‌های Swagger
ایجاد مستندات قابل فهم برای سرویس‌ها و رابط‌های برنامه نویسی
تست و اعتبارسنجی وب سرویس‌ها با استفاده از Swagger UI
سهولت در نگهداری و به‌روزرسانی مستندات سرویس‌ها

3.مفهوم و اهمیت مستندسازی API

مستندسازی API به معنای ایجاد مستنداتی است که برنامه‌نویسان و توسعه‌دهندگان می‌توانند از آن‌ها برای درک و استفاده از رابط برنامه‌نویسی در پروژه‌های خود استفاده کنند. ایجاد مستندات مفصل و قابل فهم برای APIها، ارتباط بین توسعه‌دهندگان را سهولت می‌بخشد و بهبود همکاری و درک مشترک در تیم‌های برنامه‌نویسی را فراهم می‌کند.

4.نصب سواگر در پروژه لاراول

برای شروع استفاده از سواگر در پروژه لاراول، ابتدا باید پکیج مربوطه را نصب کنید. با استفاده از ابزار Composer، می‌توانید دستور زیر را اجرا کنید:

composer require --dev darkaonline/l5-swagger

با اجرای دستور زیر می توانید پیکربندی Swagger را منتشر کنید و فایل ها را در پروژه خود مشاهده کنید:

php artisan vendor:publish --provider  "L5Swagger\L5SwaggerServiceProvider

حالا که سواگر نصب شده و تنظیمات اولیه انجام شده است، می‌توانید شروع به تولید مستندات کنید.

قبل از آن باید در روت اصلی این موارد را به داکیومنت های متد کنترلر خود اضافه کنید. برای مثال:

ابتدا یک روت تعریف کنید:

 Route::get("/" , [HomeController::class , 'index']);

سپس داکیومنت زیر را به متد index اضافه کنید:

  /**
     * @OA\PathItem(path="/api/v1")
     *
     * @OA\Info(
     *      version="0.0.0",
     *      title="Anophel API Documentation"
     *  )
     */
    public function index(): string
    {
        return "API";
    }

حال بدون مشکل و باگ، دستور زیر را برای ایجاد دایکومنت اضافه کنید. برای این کار، می‌توانید از دستورات زیر استفاده کنید:

php artisan swagger:generate

این دستور، مستندات مربوط به رابط‌های برنامه نویسی شما را تولید می‌کند و آنها را در مسیر تعیین شده ذخیره می‌کند.

حال برای دسترسی به swagger ui به روت زیر بروید:

http://localhost:8000/api/documentation

در این روت API هایی که برای آن ها داکیومنت نوشته اید را خواهید داد. حال برویم یک API بنویسم و نحوه نوشتن داکیومنت سواگر برای آن را یاد بگیریم. اگر با API نویسی در لاراول آشنا نیستید این مقاله را بررسی کنید.

تنظیم Swagger در لاراول

پس از نصب پکیج darkaonline/l5-swagger، باید تنظیمات مربوطه را در فایل config/swagger.php اعمال کنید. این فایل حاوی تمامی تنظیمات مورد نیاز برای فعال‌سازی و تنظیم Swagger در لاراول است. برای نمونه، می‌توانید تنظیمات زیر را در فایل config/swagger.php قرار دهید:

return [
    'defaults' => [
        'routes' => true,
        'register' => true,
        'api' => true,
        'paths' => [
            'docs' => 'docs',
            'api' => 'api-docs',
            'oauth2_callback' => 'api/oauth2-callback',
        ],
    ],
];

با تنظیمات فوق، شما می‌توانید به راحتی از Swagger در لاراول استفاده کنید. برای دسترسی به صفحه‌ی Swagger UI، کافیست به آدرس http://your-domain.com/api/documentation بروید. در این صفحه، می‌توانید تمامی روش‌ها، پارامترها و مستندات مربوط به API خود را مشاهده کنید و همچنین از قابلیت‌های تست و تعاملی Swagger استفاده کنید.

تعریف مسیرها و پارامترها

با استفاده از سواگر، می‌توانید مسیرها و پارامترهای API خود را توصیف کنید. این ابزار از فرمت YAML یا JSON برای تعریف مستندات استفاده می‌کند. به عنوان مثال:

paths:
  /users:
    get:
      summary: get list of users
      responses:
        '200':
          description: Succsesfully

توضیح و نوع داده‌ها

سواگر امکان توضیح و نوع داده‌هایی که در API استفاده می‌شوند را فراهم می‌کند. می‌توانید برای هر پارامتر و نوع داده توضیحاتی اضافه کنید تا برنامه‌نویسان بتوانند به راحتی درک کنند. به عنوان مثال:

parameters:
  - name: username
    in: query
    description: username
    required: true
    schema:
      type: string

مثال از استفاده از سواگر در auth در لاراول همراه با مستند سازی :

<?php
namespace App\Http\Controllers\Api;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
use Hash;
use App\User;
class AuthController extends Controller
{
      /**
        * @OA\Post(
        * path="/api/register",
        * operationId="Register",
        * tags={"Register"},
        * summary="User Register",
        * description="User Register here",
        *     @OA\RequestBody(
        *         @OA\JsonContent(),
        *         @OA\MediaType(
        *            mediaType="multipart/form-data",
        *            @OA\Schema(
        *               type="object",
        *               required={"name","email", "password", "password_confirmation"},
        *               @OA\Property(property="name", type="text"),
        *               @OA\Property(property="email", type="text"),
        *               @OA\Property(property="password", type="password"),
        *               @OA\Property(property="password_confirmation", type="password")
        *            ),
        *        ),
        *    ),
        *      @OA\Response(
        *          response=201,
        *          description="Register Successfully",
        *          @OA\JsonContent()
        *       ),
        *      @OA\Response(
        *          response=200,
        *          description="Register Successfully",
        *          @OA\JsonContent()
        *       ),
        *      @OA\Response(
        *          response=422,
        *          description="Unprocessable Entity",
        *          @OA\JsonContent()
        *       ),
        *      @OA\Response(response=400, description="Bad request"),
        *      @OA\Response(response=404, description="Resource Not Found"),
        * )
        */
      public function register(Request $request)
      {
          $validation= $request->validate([
              'name' => 'required',
              'email' => 'required|email|unique:users',
              'password' => 'required|confirmed',
              'mobile_number' => 'required',
          ]);
          $data = $request->all();
          $data['password'] = Hash::make($data['password']);
          $user = User::create($data);
          $success['token'] =  $user->createToken('authToken')->accessToken;
          $success['name'] =  $user->name;
          return response()->json(['success' => $success]);
      }
      /**
        * @OA\Post(
        * path="/api/login",
        * operationId="authLogin",
        * tags={"Login"},
        * summary="User Login",
        * description="Login User Here",
        *     @OA\RequestBody(
        *         @OA\JsonContent(),
        *         @OA\MediaType(
        *            mediaType="multipart/form-data",
        *            @OA\Schema(
        *               type="object",
        *               required={"email", "password"},
        *               @OA\Property(property="email", type="email"),
        *               @OA\Property(property="password", type="password")
        *            ),
        *        ),
        *    ),
        *      @OA\Response(
        *          response=201,
        *          description="Login Successfully",
        *          @OA\JsonContent()
        *       ),
        *      @OA\Response(
        *          response=200,
        *          description="Login Successfully",
        *          @OA\JsonContent()
        *       ),
        *      @OA\Response(
        *          response=422,
        *          description="Unprocessable Entity",
        *          @OA\JsonContent()
        *       ),
        *      @OA\Response(response=400, description="Bad request"),
        *      @OA\Response(response=404, description="Resource Not Found"),
        * )
        */
      public function login(Request $request)
      {
          $validation= $request->validate([
              'email' => 'email|required',
              'password' => 'required'
          ]);
          if (!auth()->attempt($validation)) {
              return response()->json(['error' => 'Unauthorised'], 401);
          } else {
              $success['token'] = auth()->user()->createToken('authToken')->accessToken;
              $success['user'] = auth()->user();
              return response()->json(['success' => $success])->setStatusCode(200);
          }
      }
}

جهت آشنایی با اهمیت تجربه کاربری در API نویسی می توانید از این مقاله استفاده کنید.

نتیجه‌

در این مقاله، به بررسی سواگر (Swagger) و استفاده آن در فریم‌ورک لاراول (Laravel) پرداختیم. سواگر به شما امکان می‌دهد مستندات API خود را به صورت خودکار تولید کنید و تست و اجرای درخواست‌ها را بدون نیاز به برنامه خارجی انجام دهید. با استفاده از سواگر، همکاری و درک سریع توسعه‌دهندگان افزایش می‌یابد و می‌توانید مستندات دقیق و قابل فهمی را برای API خود فراهم کنید.

استفاده از سواگر در لاراول نیز بسیار آسان است. با نصب پکیج مربوطه و تعریف مسیرها و کنترلرها، می‌توانید مستندات API خود را به راحتی تولید کنید و از ویژگی‌های سواگر برای تست و اجرای درخواست‌ها استفاده کنید.

اگر شما هم یک توسعه‌دهنده هستید و در پروژه‌های خود از سواگر استفاده نمی‌کنید، پیشنهاد می‌کنم آن را امتحان کنید. سواگر به شما کمک می‌کند تا فرآیند مستندسازی و تست API را ساده‌تر و کارآمدتر انجام دهید و به همکاران خود راحتی و قابلیت درک بیشتری ارائه دهید.