دليل شامل لاستخدام Swagger في توثيق RESTful APIs

مقدمة

مع تزايد استخدام واجهات برمجة التطبيقات (APIs) في تطوير التطبيقات، أصبح من الضروري وجود أدوات تساعد في توثيقها واختبارها بسهولة. Swagger هي واحدة من أشهر الأدوات المستخدمة في توثيق RESTful APIs، حيث توفر واجهة تفاعلية تسهل على المطورين استكشاف وتجربة واجهات API مباشرة دون الحاجة إلى كتابة أكواد إضافية.

في هذا المقال، سنتعرف على Swagger، مكوناته، كيفية استخدامه مع Django REST Framework (DRF) وFastAPI، وأهم ميزاته التي تجعل تطوير واجهات API أكثر كفاءة وتنظيمًا.

ما هو Swagger؟

Swagger هو إطار عمل مفتوح المصدر يُستخدم لإنشاء وتوثيق RESTful APIs بشكل تفاعلي. يعتمد على OpenAPI Specification (OAS)، مما يجعله أداة قياسية لإنشاء توثيق متكامل لواجهات API.

يسمح Swagger للمطورين بتحديد هيكل API باستخدام ملفات YAML أو JSON، مما يسهل فهم كيفية عمل الواجهة البرمجية، أنواع الطلبات المدعومة، المعاملات، ونماذج الاستجابات.

مكونات Swagger

يتكون Swagger من عدة أدوات تساعد في إنشاء وتوثيق واختبار واجهات API، ومن أهمها:

1. Swagger UI

   • أداة توفر واجهة رسومية تفاعلية لاستكشاف وتجربة واجهات API بسهولة.
   • تتيح للمستخدمين إرسال الطلبات والحصول على الردود مباشرةً من خلال المتصفح.

2. Swagger Editor

   • بيئة تحرير عبر الإنترنت تتيح لك كتابة ملفات OpenAPI بتنسيق YAML أو JSON ومشاهدتها مباشرةً.

3. Swagger Codegen

   • أداة تولّد كود العميل والخادم من ملفات OpenAPI بأكثر من لغة برمجة مثل Python, Java, JavaScript وغيرها.

4. Swagger Hub

   • منصة سحابية توفر ميزات تعاونية لإنشاء ومشاركة توثيق API بين فرق العمل.

أهمية استخدام Swagger

استخدام Swagger يوفر العديد من المزايا، من بينها:

✔ توثيق تلقائي: يقلل الحاجة إلى كتابة مستندات API يدويًا.
✔ تحسين تجربة المطورين: يوفر واجهة سهلة لفهم كيفية استخدام الواجهات البرمجية.
✔ التوافق مع معايير OpenAPI: يسهل التكامل مع أدوات أخرى تعتمد على المواصفات نفسها.
✔ إمكانية اختبار API: يتيح تجربة الطلبات والإجابات دون الحاجة إلى أدوات خارجية.
✔ توليد أكواد جاهزة: يمكن استخدامه لإنشاء أكواد Client وServer للعديد من اللغات.

كيفية استخدام Swagger مع Django REST Framework (DRF)

إذا كنت تستخدم Django REST Framework، فيمكنك إضافة Swagger بسهولة باستخدام مكتبة drf-yasg.

1. تثبيت drf-yasg

قم بتثبيت الحزمة باستخدام pip:

pip install drf-yasg

2. إعداد urls.py

أضف التكوينات التالية لإنشاء صفحة توثيق Swagger:

from django.urls import path, re_path
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="API Documentation",
        default_version="v1",
        description="توثيق API باستخدام Swagger",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="[email protected]"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='swagger-ui'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='redoc-ui'),
]

بعد تشغيل السيرفر، يمكنك الوصول إلى التوثيق عبر:

• Swagger UI: http://127.0.0.1:8000/swagger/
• ReDoc UI: http://127.0.0.1:8000/redoc/

استخدام Swagger مع FastAPI

إذا كنت تعمل بـ FastAPI، فإن Swagger UI مدمج بشكل افتراضي، ولا تحتاج إلى إعدادات إضافية.

مثال عملي لإنشاء API موثقة تلقائيًا

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}", summary="الحصول على عنصر", description="إرجاع عنصر محدد عبر معرفه.")
def read_item(item_id: int):
    return {"item_id": item_id, "name": "Item Name"}

بعد تشغيل التطبيق، يمكنك الوصول إلى التوثيق عبر:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

تخصيص مستندات Swagger

يمكنك تخصيص التوثيق بإضافة أوصاف، معلمات، ونماذج استجابة. على سبيل المثال:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str
    price: float
    available: bool

@app.post("/items/", response_model=Item, summary="إضافة عنصر جديد")
def create_item(item: Item):
    return item

هذا الكود سيظهر في Swagger UI مع تفاصيل عن الطلبات والاستجابات المتاحة.

خاتمة

Swagger هو أداة قوية وضرورية لأي مطور يعمل على RESTful APIs، حيث يوفر توثيقًا ديناميكيًا يساعد في فهم واختبار الواجهات البرمجية بسهولة. سواء كنت تستخدم Django REST Framework أو FastAPI، فإن دمج Swagger في مشروعك سيجعل عملية التطوير أكثر كفاءة وتنظيمًا.

إذا كنت ترغب في تجربة Swagger في مشروعك، جرب الخطوات المذكورة أعلاه وابدأ في توثيق APIs الخاصة بك باحترافية!