استفاده از 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 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 کنید تا این مشکل برطرف شود.

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