استفاده از 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
توسعهدهندگان دربارهی ما چه میگویند
تجربه کار باliara_cloud@امروز خیلی خوب بود. یکی از سرویس هام رو منتقل کردم روش و راضیم. انقد سریع و جذاب کارم راه افتادم اصن باورم نمیشد! برعکس سرویس های PaaS دیگه با اون همه پیچیدگیشون. دمتون گرم
...
MohammadReza
keikaavousi
بعد از بسته شدن @fandoghpaas و ناراحتی همهمون از اینکه یه سرویس خوب و صادق نمیتونه از پس هزینهها بر بیاد، سرویسم رو منتقل کردم به پاس لیارا (https://liara.ir @liara_cloud) . تجربه راحت و خوب. تفاوتهایی داشت که کمی کار میخواست ولی تا الان کاملا راضی.
jadi
jadi
یه خسته نباشید باید به تصمیمliara_cloud@بگم،
بعد از چندین روز سرکله زدن با سرویس های مشابه بالاخره تصمیم گرفتم لیارا رو امتحان کنم و باور نمیشه ۱۰ دقیقه بیشتر وقت نبرد،
دمتون گرم.
Arch
EbadiDev
واسه سرویس PaaS با اختلاف لیارا بهترین رابط کاربری داره و یکی از مزیتهای سرویس دیتابیسشون اینه که خودشون به صورت دورهای بکآپ میگیرن.
...
Ali Najafi
me_ali_najafi
یکی از کارهای خوبی که جدیداً میکنم اینه که یه دیتابیس روی لیارا میسازم و به پروژه وصل میکنم اینطوری هم خونه و هم محل کار دیتابیس بروز رو دارم و راحت میتونم ادامه بدم کار روliara_cloud@
Navid
1navid
عاشقliara_cloud@شدم درسته در حد AWS نیست ولی خب تجربه خوبی واسه پروژه های داخل ایران ارائه میده، میتونم رو CD هم اجراش کنم
Amir H Shekari
vanenshi