استفاده از Swagger در Laravel برای ایجاد RESTful API

به هنگام ایجاد یک API، اینکه یک رابط کاربری شبیه‌سازی شده برای API در اختیار کاربران قرار دهید، همیشه ایده خوبی است. این موضوع بهتر می‌شود اگر توسط این رابط شبیه‌سازی شده، کاربران بتوانند API را تست و بررسی کنند. OAuth 2.0 Playground گوگل، مثال خوبی از این موضوع است.

Swagger یک زبان/فریم‌ورک برای ساخت و شبیه‌سازی RESTful APIها است. این روز‌ها Laravel و Lumen در حال تبدیل شدن به معروف‌ترین فریم‌ورک‌ها برای ایجاد برنامه‌ها و APIها با PHP هستند، در نتیجه انتظار داریم که این‌ها در Swagger پشتیبانی شوند، اما چنین چیزی را پیدا نکردیم. به‌هر‌حال، Swagger UI و Swagger Specification، بسیار کاربرپسند هستند و در این مقاله قصد داریم تا به صورت دستی، خودمان برای API، آن را بنویسیم.

در ادامه خواهید خواند:

• نصب
• تنظیمات (Swagger Specification)
• نسخه جدید Swagger (OpenAPI 3)
• جمع بندی

نصب

می‌توانید Swagger UI را با دانلود یا clone کردن از مخزن، نصب کنید. بعد از آن ./dist/index.html را در مرورگر خود باز کنید. برای دریافت اطلاعات بیشتر در رابطه با شخصی‌سازی Swagger، می‌توانید به این لینک مراجعه کنید.

تنظیمات (Swagger Specification)

تنظیمات Swagger شامل یک فایل YAML یا JSON است. Swagger Editor (یک ویرایشگر برای تغییر تنظیمات Swagger با خروجی Real-time) در طول فرآیند استفاده از Swagger برای APIتان، می‌تواند بسیار مفید باشد، همچنین می‌توانید از آن به عنوان ویرایشگر اصلی خود برای ایجاد تنظیمات Swagger استفاده کنید. کد زیر، مثالی از یک فایل YAML برای تنظیمات Swagger است:

swagger: '2.0'  
info:  
  title: API  
  description: Move your app forward with the Liara
schemes:  
  - http  
produces:  
  - application/json  
tags:  
- name: "User"  
- name: "Authentication"  
  description: "API Authentication related calls"  
paths:  
  /auth/login:  
    post:  
      summary: Login user   
      description:   
      tags:  
        - Authentication  
      parameters:  
        - $ref: 'params.yaml#/EmailPost'  
        - $ref: 'params.yaml#/PasswordPost'  
          
  /user:  
    post:  
      summary: Create a new user   
      description:   
      tags:  
        - User  
      parameters:  
        - $ref: 'params.yaml#/NamePost'  
        - $ref: 'params.yaml#/EmailPost'  
        - $ref: 'params.yaml#/PasswordPost'  
      responses:  
            200:  
              $ref: 'responses.yaml#/BasicSuccess'    
  /user/{id}:  
    post:  
      summary: update a user  
      tags:  
        - User  
      parameters:  
        - name: id  
          in: path  
          required: true  
          type: integer            
        - $ref: 'params.yaml#/NamePost'          
      responses:  
        200:  
          description: OK  
  
  /user/forgotPassword:  
    post:  
      summary: forgot password  
      description:   
      tags:  
        - User          
      parameters:  
        - $ref: 'params.yaml#/EmailPost'  
      responses:  
            200:  
              $ref: 'responses.yaml#/BasicSuccess'    

همانطور که مشاهده می‌کنید، می‌توانیم از بخش‌های مختلف، توسط ویژگی $ref، مجددا استفاده کنیم. همچنین این فایل می‌تواند به فایل‌های کوچک‌تری تقسیم شود، همانطور که چندین فایل را در این فایل تعریف کردیم (params.yaml و responses.yaml).

بخشی از فایل params.yaml:

NamePost:  
    name: name  
    in: formData  
    description: description  
    type: string      
PasswordPost:  
    name: password  
    in: formData  
    required: true  
    type: string      
EmailPost:  
    name: email  
    in: formData  
    description: description  
    type: string

نتیجه باید مشابه تصویر زیر باشد:

Swagger UI یک پروژه فعال و بروز است، پس توصیه می‌کنیم که همیشه در APIهایتان از آن استفاده کنید. اما توجه داشته باشید که برخی از ویژگی‌ها و قابلیت‌های جزئی، ممکن است در build برنامه‌تان کار نکند، پس همه چیز را تست کنید. همچنین گاهی اوقات ممکن است تغییرات را در فایل تنظیمات مشاهده نکنید که این موضوع ممکن است به دلیل cache مرورگرتان باشد. می‌توانید صفحه را hard-reload کنید تا این مشکل برطرف شود.

زیرساختی پایدار برای میزبانی پروژه‌های Laravel
✅ سازگار با Queue، Scheduler و ابزارهای توسعه✅ دیپلوی مستقیم از GitHub✅ پشتیبانی از اتصال به دیتابیس‌های مختلف
خرید و راه‌اندازی هاست لاراول

نسخه جدید Swagger (OpenAPI 3)

Swagger از نسخه ۲.۰ به بعد، تحت عنوان OpenAPI Specification 3 یا به اختصار OpenAPI 3 توسعه داده شده است. این نسخه با هدف بهبود ساختار و افزایش قابلیت‌های مستندسازی APIها معرفی شده و در حال حاضر به استاندارد رایج‌تری نسبت به نسخه‌های قبلی تبدیل شده است.

در OpenAPI 3، ساختار بخش‌هایی مانند ارسال داده‌ها تغییر یافته و به‌جای استفاده از formData، از بخش requestBody استفاده می‌شود که قابلیت تعریف دقیق‌تر نوع داده و قالب آن را فراهم می‌کند. برای مثال:

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        properties:
          email:
            type: string
          password:
            type: string

این نسخه همچنین از مفاهیم جدیدی مانند components برای تعریف مشترک بخش‌هایی مانند پارامترها، پاسخ‌ها و اسکیماها پشتیبانی می‌کند و امکان ساخت مستندات ماژولارتر و خواناتر را فراهم می‌سازد.

در صورتی که از نسخه‌ی ۲ استفاده می‌کنید، ابزارهایی برای تبدیل فایل‌های Swagger 2.0 به OpenAPI 3 نیز در دسترس هستند. با توجه به پشتیبانی کامل Swagger UI از OpenAPI 3، توصیه می‌شود در پروژه‌های جدید خود از این نسخه بهره بگیرید تا مستندسازی API به شکلی دقیق‌تر و استانداردتر انجام شود.

هاست ابری PHP برای اجرای سریع و امن اپلیکیشن‌ها
✅ پشتیبانی کامل از PHP ۸ و Composer✅ قابلیت اتصال به انواع پایگاه داده✅ دیپلوی آسان از طریق Git یا CLI
خرید و راه‌اندازی هاست PHP

جمع بندی

اگر در حال ساخت یک API هستید، داشتن مستندات خوب یکی از مهم‌ترین کارهاست. مستندسازی باعث می‌شود دیگران راحت‌تر بفهمند چطور باید از API شما استفاده کنند، بدون اینکه لازم باشد وارد کد شوند. ابزار Swagger کمک می‌کند تا این مستندات را به شکلی خوانا و قابل‌تست بسازید.

در این مقاله دیدیم که چطور می‌شود Swagger UI را راه‌اندازی کرد، تنظیمات لازم را با فرمت YAML نوشت و حتی بخش‌هایی مثل پارامترها و پاسخ‌ها را به صورت جداگانه مدیریت کرد. همچنین به نسخه جدید Swagger یعنی OpenAPI 3 اشاره کردیم که امکانات بهتری دارد و مستندسازی را دقیق‌تر و حرفه‌ای‌تر می‌کند.

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

منبع: https://www.cloudways.com/blog/use-swagger-with-laravel-based-restful-api