توثيق الـ API: كيفية قراءة مستندات Swagger و Redoc

يا هلا بالجميع! كثير منّا كـ مبرمجين نتعامل مع الـ APIs بشكل يومي. لكن عشان تستخدم أي API صح، لازم تفهم توثيقه (Documentation). اليوم بنتكلم عن أشهر أداتين للتوثيق: Swagger UI و Redoc، وكيف تقراها وتستفيد منها بأقصى شكل.

وش هو Swagger / OpenAPI؟

باختصار، OpenAPI هي مواصفة (Specification) قياسية لوصف الـ APIs. يعني طريقة موحدة عشان توصف الـ API حقك: وش يسوي، وش ياخذ، وش يرجع. Swagger هي مجموعة أدوات (Tools) مبنية على هالـ OpenAPI specification، أشهرها Swagger UI اللي يعرض التوثيق بشكل تفاعلي تقدر تجربه مباشرة.

كيف تقرا مستندات Swagger UI؟

لما تفتح صفحة Swagger UI، بتشوف قدامك قائمة طويلة من الأقسام. كل قسم يمثل مجموعة من الـ Endpoints (نقاط النهاية) اللي لها علاقة ببعض، مثلاً User، Products، وهكذا.

الـ Endpoints (نقاط النهاية)

كل Endpoint يمثل عملية معينة (مثل إضافة مستخدم، جلب منتجات). بتشوفها مقسمة حسب طريقة الطلب (HTTP Method):

  • GET: لجلب البيانات.
  • POST: لإضافة بيانات جديدة.
  • PUT: لتحديث بيانات موجودة بالكامل.
  • PATCH: لتحديث جزء من بيانات موجودة.
  • DELETE: لحذف بيانات.

كل مربع Endpoint تقدر تضغط عليه عشان تشوف التفاصيل.

الـ Parameters (المتغيرات)

داخل كل Endpoint، بتشوف قسم للـ Parameters (المتغيرات) اللي يحتاجها الطلب. هذي ممكن تكون أنواع مختلفة:

  • Path Parameters: جزء من الرابط نفسه، زي GET /users/{id}، هنا {id} هو الـ Path Parameter.
  • Query Parameters: تجي بعد علامة الاستفهام ? في الرابط، زي GET /products?category=electronics.
  • Header Parameters: معلومات إضافية ترسلها في رأس الطلب (Headers)، وغالباً تستخدم للتوثيق (Authentication) أو معلومات الـ Client.
  • Request Body: للطلبات اللي ترسل فيها بيانات معقدة (عادةً مع POST, PUT, PATCH)، وتكون بصيغة JSON.

الـ Request Body (الـ Schemas والأمثلة)

إذا كان الـ Endpoint يتطلب Request Body، بتشوف قسم يوضح لك شكل البيانات المتوقع. عادةً بيكون فيه:

  • Schema: يوضح لك كل حقل (Field)، نوعه (String, Integer, Boolean, Object, Array)، وهل هو إجباري (required) أو اختياري.
  • Example Value: مثال جاهز تقدر تنسخه وتعدل عليه عشان تجربه.

تقدر تجرب الطلب مباشرة من Swagger UI عن طريق زر Try it out وتعبئة البيانات ثم Execute.

الـ Responses (الاستجابات)

بعد قسم الـ Parameters، بتشوف قسم الـ Responses (الاستجابات). هذا القسم مهم جداً لأنه يوضح لك وش بيرجع الـ API بناءً على حالة الطلب (HTTP Status Code).

  • 200 OK: يعني الطلب نجح وكل شيء تمام.
  • 201 Created: يعني تم إنشاء مورد جديد بنجاح.
  • 400 Bad Request: يعني في مشكلة بالبيانات اللي أرسلتها.
  • 401 Unauthorized: يعني ما عندك صلاحية للوصول (تحتاج توثيق).
  • 403 Forbidden: يعني عندك توثيق بس ما عندك صلاحية لهالعملية.
  • 404 Not Found: يعني المورد اللي طلبته مو موجود.
  • 500 Internal Server Error: يعني في مشكلة داخلية بالخادم.

لكل Status Code، بتشوف Schema و Example Value للي بيرجع لك الـ API.

الـ Authentication (التوثيق)

إذا كان الـ API يتطلب توثيق (مثل Token)، بتشوف زر Authorize فوق. تضغط عليه وتدخل بيانات التوثيق حقتك (API Key, Bearer Token) عشان تقدر تجرب الـ Endpoints المقفلة.

مثلاً، لو عندك POST /users:

  1. تضغط على المربع الخاص بـ POST /users.
  2. تضغط على زر Try it out.
  3. بتشوف Request Body، تعبي بيانات المستخدم الجديد (مثلاً name, email, password).
  4. تضغط Execute.
  5. بتشوف الـ Curl command اللي تنفذ، و Request URL، و Server response (الاستجابة).

طيب، وش قصة Redoc؟

Redoc هي أداة ثانية تعرض لك نفس مواصفات OpenAPI، لكن بتصميم مختلف يركز على سهولة القراءة. كثير يشوفونها أفضل للتوثيق العام لأنها أشبه بصفحة ويب عادية، بينما Swagger UI ممتاز للتجربة والتفاعل.

كيف تقرا مستندات Redoc؟

لما تفتح صفحة Redoc، بتلاحظ الآتي:

ثلاثة أعمدة (عادةً)

  • العمود الأيسر (Navigation): قائمة بجميع الـ Endpoints والمجموعات، تقدر تتنقل بينهم بسهولة.
  • العمود الأوسط (Content): هو المحتوى الرئيسي اللي فيه تفاصيل الـ Endpoint اللي اخترته، نفس معلومات Swagger (الوصف، الـ Parameters، الـ Request Body، الـ Responses).
  • العمود الأيمن (Examples): يعرض لك أمثلة جاهزة للطلبات والاستجابات، غالباً بصيغة Curl أو لغات برمجة ثانية، وهذا يسهل عليك كثير لما تنسخ وتجرب.

Redoc تتميز بتصميمها النظيف وسهولة التنقل، كل شيء واضح تحت بعضه بدون الحاجة لفتح وإغلاق أقسام كثيرة زي Swagger UI.

نصايح عشان تقرا التوثيق صح:

1. ابدأ بالوصف العام: اقرا وصف الـ API ككل عشان تفهم وش يسوي.

2. ركز على الـ Endpoints اللي تحتاجها: لا تحاول تفهم كل شيء دفعة واحدة.

3. انتبه للـ Parameters: تأكد من أنواعها وهل هي required أو لا.

4. افهم الـ Schemas: خصوصاً للـ Request Body و Responses عشان تعرف وش ترسل ووش تتوقع.

5. لا تخاف تجرب: استخدم Try it out في Swagger UI عشان تشوف الـ API وهو شغال.

6. شوف الـ Status Codes: عشان تعرف كيف تتعامل مع الأخطاء والاستجابات المختلفة.

الخلاصة

سواء كنت تستخدم Swagger UI أو Redoc، الهدف واحد: تفهم كيف تتعامل مع الـ API. كل أداة لها مميزاتها، لكن لما تفهم الأساسيات اللي ذكرناها، بتصير قراءة أي توثيق API سهل عليك. بالتوفيق يا وحوش البرمجة!