اختبار API باستخدام Swagger و curl

الفصل الأول: مقدمة – لماذا نختبر الـ API؟

في الدروس السابقة، بنينا API كامل لإدارة المهام باستخدام FastAPI، وربطناه بقاعدة بيانات SQLite، وأضفنا التحقق من البيانات ومعالجة الأخطاء. لكن كيف نضمن أن كل شيء يعمل كما ينبغي؟ هنا يأتي دور اختبار الـ API.

اختبار الـ API هو عملية التحقق من أن كل نقطة نهاية (endpoint) في تطبيقك تستجيب بالشكل الصحيح، وتتعامل مع البيانات بشكل سليم، وتتعامل مع الأخطاء كما هو متوقع. بدون اختبار، قد تكتشف مشاكل بعد أن يصبح التطبيق في الإنتاج، مما قد يسبب مشاكل للمستخدمين.

لماذا نحتاج إلى اختبار الـ API؟

• ضمان الجودة: التأكد من أن كل عملية (إنشاء، قراءة، تحديث، حذف) تعمل بشكل صحيح.
• اكتشاف الأخطاء مبكراً: بدلاً من انتظار المستخدم ليخبرك بوجود مشكلة.
• تسهيل التطوير المستقبلي: عندما تضيف ميزات جديدة، يمكنك التأكد من أنك لم تكسر شيئاً قديماً.
• توثيق حي: أدوات مثل Swagger توفر واجهة تفاعلية يمكن لأي شخص استخدامها لفهم API الخاص بك.

ما الذي سنتعلمه في هذا الدرس؟

في هذا الدرس، سنتعلم طريقتين أساسيتين لاختبار الـ API الخاص بنا:

• Swagger UI: واجهة رسومية تفاعلية تأتي مدمجة مع FastAPI، تسمح لك بتجربة كل endpoint مباشرة من المتصفح.
• curl: أداة سطر أوامر قوية تسمح لك بإرسال طلبات HTTP من التيرمينال، وهي مفيدة جداً للأتمتة والاختبار السريع.

خطوات التنفيذ

1. تشغيل الخادم المحلي

أولاً، تأكد من أن مشروع FastAPI الخاص بك يعمل. افتح التيرمينال في مجلد المشروع، وقم بتشغيل الخادم باستخدام الأمر التالي:

uvicorn main:app --reload

سيبدأ الخادم على المنفذ 8000 افتراضياً. اتركه يعمل في الخلفية.

2. اختبار API باستخدام Swagger UI

Swagger UI هو أحد أقوى مميزات FastAPI. بمجرد تشغيل الخادم، يمكنك الوصول إليه عبر الرابط التالي في المتصفح:

http://127.0.0.1:8000/docs

ستظهر لك واجهة جميلة تعرض جميع endpoints المتاحة في مشروعك. كل endpoint له زر "Try it out" يسمح لك بتجربته مباشرة.

مثال عملي: إنشاء مهمة جديدة باستخدام Swagger

1. اذهب إلى قسم POST /tasks.
2. اضغط على "Try it out".
3. في حقل "Request body"، اكتب البيانات التالية:

{
  "title": "اختبار Swagger",
  "description": "هذه مهمة تجريبية",
  "completed": false
}

4. اضغط على "Execute".
5. سترى الرد (Response) في الأسفل. يجب أن ترى رمز الحالة 201 Created مع بيانات المهمة الجديدة.

3. اختبار API باستخدام curl

curl هي أداة سطر أوامر موجودة في معظم أنظمة التشغيل (Linux, macOS, Windows). تسمح لك بإرسال طلبات HTTP دون الحاجة إلى متصفح.

مثال عملي: إنشاء مهمة جديدة باستخدام curl

افتح نافذة تيرمينال جديدة (مع ترك الخادم يعمل في النافذة الأولى)، واكتب الأمر التالي:

curl -X POST "http://127.0.0.1:8000/tasks" \
     -H "Content-Type: application/json" \
     -d '{"title": "اختبار curl", "description": "مهمة من التيرمينال", "completed": false}'

سيظهر الرد مباشرة في التيرمينال. يجب أن ترى شيئاً مثل:

{"id":1,"title":"اختبار curl","description":"مهمة من التيرمينال","completed":false}

اختبار عمليات أخرى باستخدام curl

جلب جميع المهام (GET):

curl -X GET "http://127.0.0.1:8000/tasks"

جلب مهمة محددة (GET by ID):

curl -X GET "http://127.0.0.1:8000/tasks/1"

تحديث مهمة (PUT):

curl -X PUT "http://127.0.0.1:8000/tasks/1" \
     -H "Content-Type: application/json" \
     -d '{"title": "مهمة محدثة", "description": "تم التحديث", "completed": true}'

حذف مهمة (DELETE):

curl -X DELETE "http://127.0.0.1:8000/tasks/1"

أخطاء شائعة وكيفية تجنبها

• الخادم لا يعمل: تأكد من أنك قمت بتشغيل uvicorn وأنه لا توجد أخطاء في التيرمينال.
• خطأ في عنوان URL: تأكد من أنك تستخدم http://127.0.0.1:8000 وليس https.
• تنسيق JSON غير صحيح: في curl، تأكد من استخدام علامات التنصيص المزدوجة (") داخل JSON، وأن الهيكل صحيح.
• نوع المحتوى (Content-Type) مفقود: في طلبات POST و PUT، يجب إضافة الرأس -H "Content-Type: application/json".
• المنفذ مشغول: إذا كان المنفذ 8000 مستخدماً من قبل تطبيق آخر، يمكنك تغييره باستخدام uvicorn main:app --reload --port 8001.

تمرين صغير

خلاصة

في هذا الدرس، تعلمنا كيف نختبر API الخاص بنا بطريقتين: باستخدام Swagger UI (الواجهة الرسومية) و curl (سطر الأوامر). كلتا الطريقتين ضروريتان لأي مطور API. Swagger رائع للاستكشاف السريع والتوثيق، بينما curl مثالي للأتمتة والاختبار في بيئات الإنتاج. في الدرس القادم، سنقوم ببناء مشروع Tasks API النهائي وتجهيزه للتطوير المستقبلي.