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


۱۳ مرداد ۱۳۹۹
استفاده از 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 برای یک برنامه laravel

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

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

برچسب‌ها:

خدمات رایگان لیارا

۲.۵ گیگابایت فضای ذخیره‌سازی ابری رایگان

۲.۵ گیگابایت Object Storage سازگار با پروتکل S3 با دیسک‌های SSD به‌صورت رایگان دریافت کنید.

هاست رایگان برای دیتابیس‌

دیتابیس‌های MariaDB، PostgreSQL و Redis را فقط با یک کلیک و به‌صورت رایگان تهیه کنید.

سرویس DNS رایگان

به سادگی دامنه‌تان را اضافه کنید و به صورت رایگان رکورد‌های آن را مدیریت کنید.

۱۰۰ هزار تومان اعتبار اولیه

بعد از ثبت نام در لیارا مبلغ ۱۰۰ هزار تومان اعتبار هدیه دریافت می‌کنید که با توجه به ساعتی بودن هزینه سرویس‌ها، می‌توانید تمامی خدمات پولی را برای چندین هفته رایگان استفاده کنید.

ارسال ۱۰۰ ایمیل تراکنشی رایگان در هر ماه

در سرویس ایمیل لیارا شما می‌توانید تا ۱۰۰ ایمیل رایگان در هر ماه ارسال کنید و فقط برای بیش از آن هزینه پرداخت کنید. (به‌همراه دسترسی SMTP)

هاست رایگان برای انواع وبسایت

تفاوتی ندارد برای وبسایت خود از Node استفاده می‌کنید یا Laravel و Django، در لیارا می‌توانید به صورت کاملا رایگان آن را میزبانی کنید.

توسعه‌دهندگان درباره‌ی ما چه می‌گویند

تجربه کار باliara_cloud@امروز خیلی خوب بود. یکی از سرویس هام رو منتقل کردم روش و راضیم. انقد سریع و جذاب کارم راه افتادم اصن باورم نمیشد! برعکس سرویس های PaaS دیگه با اون همه پیچیدگیشون. دمتون گرم
...

MohammadReza
liara testimonial
keikaavousi

بعد از بسته شدن @fandoghpaas و ناراحتی همه‌مون از اینکه یه سرویس خوب و صادق نمی‌تونه از پس هزینه‌ها بر بیاد، سرویسم رو منتقل کردم به پاس لیارا (https://liara.ir @liara_cloud) . تجربه راحت و خوب. تفاوت‌هایی داشت که کمی کار می‌خواست ولی تا الان کاملا راضی.

jadi
liara testimonial
jadi

یه خسته نباشید باید به تصمیمliara_cloud@بگم،
بعد از چندین روز سرکله زدن با سرویس های مشابه بالاخره تصمیم گرفتم لیارا رو امتحان کنم و باور نمیشه ۱۰ دقیقه بیشتر وقت نبرد،
دمتون گرم.

Arch
liara testimonial
EbadiDev

واسه سرویس PaaS با اختلاف لیارا بهترین رابط کاربری داره و یکی از مزیت‌های سرویس دیتابیس‌شون اینه که خودشون به صورت دوره‌ای بکآپ میگیرن.
...

Ali Najafi
liara testimonial
me_ali_najafi

یکی از کارهای خوبی که جدیداً میکنم اینه که یه دیتابیس روی لیارا میسازم و به پروژه وصل میکنم اینطوری هم خونه و هم محل کار دیتابیس بروز رو دارم و راحت میتونم ادامه بدم کار روliara_cloud@

Navid
liara testimonial
1navid

عاشقliara_cloud@شدم درسته در حد AWS نیست ولی خب تجربه خوبی واسه پروژه های داخل ایران ارائه میده، میتونم رو CD هم اجراش کنم

Amir H Shekari
liara testimonial
vanenshi