تطوير واجهات REST API
توثيق الواجهات البرمجية باستخدام OpenAPI/Swagger
توثيق الواجهات البرمجية باستخدام OpenAPI/Swagger
التوثيق الشامل والدقيق والتفاعلي أمر بالغ الأهمية لاعتماد الواجهة البرمجية وتجربة المطور. OpenAPI (المعروفة سابقًا باسم Swagger) هي المواصفة القياسية في الصناعة لوصف واجهات RESTful API. في هذا الدرس، سنستكشف كيفية إنشاء توثيق واجهة برمجية احترافية باستخدام مواصفات OpenAPI والتعليقات التوضيحية وواجهة Swagger UI وأدوات الإنشاء التلقائي.
لماذا يهم توثيق الواجهة البرمجية
التوثيق الضعيف أو المفقود هو أحد الأسباب الرئيسية التي تجعل المطورين يتخلون عن الواجهات البرمجية:
- تجربة المطور: الواجهات البرمجية الموثقة جيدًا تقلل وقت التكامل من أسابيع إلى أيام
- الخدمة الذاتية: الوثائق الجيدة تقلل طلبات الدعم وتسمح للمطورين بحل المشاكل بشكل مستقل
- الاعتماد: التوثيق الكامل يرتبط مباشرة بمعدلات اعتماد أعلى للواجهة البرمجية
- الصيانة: التوثيق يساعد فريقك الخاص على فهم وصيانة الواجهة البرمجية
- الاختبار: الوثائق التفاعلية تمكن المطورين من اختبار نقاط النهاية دون كتابة كود
أبحاث الصناعة: تظهر الدراسات أن 70٪ من المطورين يعتبرون جودة التوثيق عند اختيار واجهة برمجية. تحظى Stripe و Twilio و GitHub بالثناء على توثيقها الاستثنائي، مما ساهم بشكل مباشر في نمو نظامها البيئي للمطورين.
نظرة عامة على مواصفة OpenAPI
مواصفة OpenAPI (OAS) هي تنسيق JSON أو YAML لوصف السطح الكامل للواجهة البرمجية الخاصة بك. تتضمن وثيقة OpenAPI الكاملة:
- معلومات عامة: عنوان الواجهة البرمجية، الوصف، الإصدار، معلومات الاتصال، الترخيص
- الخوادم: عناوين URL الأساسية لبيئات الإنتاج والتطوير والاختبار
- المسارات: جميع نقاط النهاية المتاحة مع طرق HTTP الخاصة بها
- المعاملات: سلاسل الاستعلام، متغيرات المسار، الرؤوس، محتويات الطلب
- الاستجابات: رموز الحالة، مخططات الاستجابة، الأمثلة
- المخططات: نماذج البيانات وخصائصها
- الأمان: طرق المصادقة (مفاتيح API، OAuth، JWT)
- العلامات: تجميعات منطقية لنقاط النهاية ذات الصلة
بنية وثيقة OpenAPI الأساسية
هذا مثال كامل لوثيقة مواصفة OpenAPI 3.0:
# openapi.yaml
openapi: 3.0.3
info:
title: واجهة برمجية للتجارة الإلكترونية
description: |
واجهة REST API كاملة لإدارة منصة التجارة الإلكترونية.
## الميزات
- إدارة كتالوج المنتجات
- معالجة الطلبات
- مصادقة المستخدم
- عمليات سلة التسوق
## تحديد المعدل
- 1000 طلب في الساعة للمستخدمين المصادق عليهم
- 100 طلب في الساعة للمستخدمين المجهولين
version: 2.1.0
contact:
name: دعم API
email: api@example.com
url: https://example.com/support
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://api.example.com/v2
description: خادم الإنتاج
- url: https://staging-api.example.com/v2
description: خادم الاختبار
- url: http://localhost:8000/api/v2
description: خادم التطوير
tags:
- name: المنتجات
description: عمليات كتالوج المنتجات
- name: الطلبات
description: إدارة الطلبات
- name: المصادقة
description: نقاط نهاية مصادقة المستخدم
paths:
/products:
get:
tags:
- المنتجات
summary: الحصول على جميع المنتجات
description: استرداد قائمة منتجات مرقمة مع تصفية اختيارية
operationId: getProducts
parameters:
- name: page
in: query
description: رقم الصفحة للترقيم
required: false
schema:
type: integer
minimum: 1
default: 1
- name: per_page
in: query
description: عدد العناصر في الصفحة
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
'200':
description: استجابة ناجحة
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Product'
</div>
تعليقات توضيحية لـ Laravel OpenAPI باستخدام L5-Swagger
بدلاً من كتابة YAML يدويًا، يمكنك استخدام التعليقات التوضيحية PHP مباشرة في وحدات التحكم الخاصة بك. تنشئ حزمة L5-Swagger في Laravel توثيق OpenAPI من التعليمات البرمجية الخاصة بك:
التثبيت
# تثبيت L5-Swagger
composer require darkaonline/l5-swagger
# نشر التكوين
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
# إنشاء التوثيق
php artisan l5-swagger:generate
</div>
مثال على وحدة تحكم مشروحة
<?php
namespace App\Http\Controllers\Api;
use App\Models\Product;
use Illuminate\Http\Request;
use App\Http\Resources\ProductResource;
/**
* @OA\Info(
* title="واجهة برمجية للتجارة الإلكترونية",
* version="2.1.0",
* description="واجهة REST API كاملة لمنصة التجارة الإلكترونية",
* @OA\Contact(
* email="api@example.com",
* name="دعم API"
* )
* )
*
* @OA\Server(
* url="https://api.example.com/v2",
* description="خادم الإنتاج"
* )
*
* @OA\SecurityScheme(
* securityScheme="bearerAuth",
* type="http",
* scheme="bearer",
* bearerFormat="JWT"
* )
*/
class ProductController extends Controller
{
/**
* @OA\Get(
* path="/products",
* tags={"المنتجات"},
* summary="الحصول على جميع المنتجات",
* description="استرداد قائمة منتجات مرقمة مع تصفية",
* operationId="getProducts",
* @OA\Parameter(
* name="page",
* in="query",
* description="رقم الصفحة",
* required=false,
* @OA\Schema(type="integer", minimum=1, default=1)
* ),
* @OA\Response(
* response=200,
* description="استجابة ناجحة"
* )
* )
*/
public function index(Request $request)
{
$query = Product::with('category');
$products = $query->paginate($request->get('per_page', 20));
return ProductResource::collection($products);
}
}
</div>
نصيحة التنظيم: ضع تعليقات @OA\Info و @OA\Server التوضيحية في وحدة التحكم الأساسية أو وحدة تحكم توثيق مخصصة. ضع تعليقات @OA\Schema التوضيحية في نماذجك أو فئات الموارد للحصول على تنظيم أفضل.
تكامل واجهة Swagger UI
بعد إنشاء مواصفة OpenAPI الخاصة بك، ينشئ L5-Swagger تلقائيًا واجهة Swagger UI تفاعلية:
# التكوين: config/l5-swagger.php
return [
'default' => 'default',
'documentations' => [
'default' => [
'api' => [
'title' => 'توثيق واجهة برمجية للتجارة الإلكترونية',
],
'routes' => [
'api' => 'api/documentation',
],
],
],
];
# إنشاء التوثيق
php artisan l5-swagger:generate
# الوصول إلى واجهة Swagger UI على:
# http://localhost:8000/api/documentation
</div>
أدوات الإنشاء التلقائي والبدائل
بالإضافة إلى L5-Swagger، يمكن لعدة أدوات إنشاء توثيق OpenAPI:
1. Scribe - توثيق Laravel API
# تثبيت Scribe
composer require --dev knuckleswtf/scribe
# نشر التكوين
php artisan vendor:publish --tag=scribe-config
# إنشاء الوثائق
php artisan scribe:generate
</div>
يقدم Scribe مزايا على L5-Swagger:
- يستنتج الأنواع تلقائيًا من تعريفات المسار
- ينشئ استجابات مثالية من استدعاءات API الفعلية
- ينشئ توثيق HTML ثابت جميل
- يدعم تصدير مجموعة Postman
حافظ على تحديث التوثيق: التوثيق القديم أسوأ من عدم وجود توثيق. دمج إنشاء الوثائق في خط أنابيب CI/CD الخاص بك لضمان بقاء الوثائق متزامنة مع تغييرات الكود.
تمرين عملي:
- تثبيت L5-Swagger في مشروع Laravel الخاص بك باستخدام Composer
- إضافة تعليقات OpenAPI التوضيحية إلى 3 طرق وحدة تحكم على الأقل (GET، POST، PUT/PATCH)
- تحديد تعليقات مخطط توضيحية لنموذجين مع جميع خصائصهما
- توثيق المصادقة باستخدام رموز الحامل مع securitySchemes
- إضافة توثيق المعاملات بما في ذلك سلاسل الاستعلام ومعاملات المسار ومحتويات الطلب
- توثيق جميع رموز الاستجابة المحتملة (200، 201، 400، 401، 404، 422، 500)
- إنشاء مواصفة OpenAPI باستخدام php artisan l5-swagger:generate
- الوصول إلى واجهة Swagger UI واختبار نقاط النهاية بشكل تفاعلي
- إضافة أمثلة استجابة للحالات الناجحة والخطأ
- توثيق نقاط نهاية تحميل الملفات باستخدام multipart/form-data
أفضل ممارسات التوثيق
- كن شاملاً: وثق كل نقطة نهاية ومعامل واستجابة
- استخدم أوصافًا واضحة: اشرح ما يفعله كل نقطة نهاية ولماذا سيستخدمها شخص ما
- قدم أمثلة: قم بتضمين أمثلة واقعية للطلب/الاستجابة
- وثق الأخطاء: اشرح جميع رموز الخطأ المحتملة وأسبابها
- قم بتضمين حدود المعدل: وثق سياسات التحكم في المعدل والحد
- أظهر المصادقة: اشرح بوضوح كيفية مصادقة الطلبات
- قم بنسخ الوثائق: حافظ على التوثيق لجميع إصدارات API المدعومة
- أضف عينات كود: قدم أمثلة بلغات برمجة متعددة
- حافظ على تحديثه: استخدم الأدوات الآلية لإعادة إنشاء الوثائق مع كل تغيير
- اختبر الميزات التفاعلية: تحقق من أن وظيفة "جربها" تعمل بشكل صحيح
نصيحة محترف: فكر في استخدام أدوات مثل Stoplight Studio أو SwaggerHub للتحرير التعاوني لتوثيق الواجهة البرمجية. توفر هذه المنصات محررات مرئية وتحكم في الإصدار وميزات تعاون جماعي تجعل صيانة وثائق API أسهل بكثير.
الخلاصة
يحول توثيق OpenAPI/Swagger واجهتك البرمجية من صندوق أسود إلى واجهة يمكن الوصول إليها وموثقة ذاتيًا. باستخدام أدوات قائمة على التعليقات التوضيحية مثل L5-Swagger أو مولدات آلية مثل Scribe، يمكنك الحفاظ على توثيق شامل يبقى متزامنًا مع قاعدة التعليمات البرمجية الخاصة بك. تتيح واجهة Swagger UI التفاعلية للمطورين استكشاف واختبار واجهتك البرمجية دون كتابة أي كود، مما يحسن بشكل كبير تجربة المطور ومعدلات الاعتماد.