إنشاء مواصفات OpenAPI من الطلبات الحالية

إن كتابة مواصفات OpenAPI من الصفر قد يستغرق الكثير من الوقت، خاصة عندما يكون الـ API الخاص بك يعمل بالفعل ومباشرًا. ترث العديد من الفرق مشاريع ذات وثائق قليلة أو معدومة، أو تعمل مع واجهات برمجة تطبيقات (APIs) تم بناؤها بسرعة خلال مراحل التطوير المبكرة. في هذه الحالات، فإن الطريقة الأكثر عملية لإنشاء التوثيق هي توليد مواصفات OpenAPI مباشرة من طلبات API الموجودة لديك.

يشرح هذا الدليل سبب نجاح هذا النهج، وما هي الأدوات التي يمكن أن تساعد، وكيف يمكنك تحويل الطلبات الفعلية إلى مواصفات OpenAPI نظيفة وقابلة لإعادة الاستخدام يمكن لفريقك الوثوق بها.

زر

الطريقة 1: نهج "الكود أولاً"

تنجح هذه الطريقة إذا كان بإمكانك إضافة تعليقات توضيحية أو مكتبات مباشرة إلى كود تطبيق الواجهة الخلفية الخاص بك.

كيف تعمل؟

تقوم بتثبيت مكتبة في إطار عمل الويب الخاص بك تقوم بفحص الكود الخاص بك (المسارات، وحدات التحكم، والنماذج) وتوليد مواصفات OpenAPI بشكل فوري.

مكتبات شائعة:

• Node.js (Express): swagger-jsdoc أو tsoa (TypeScript OpenAPI)
• Python (FastAPI/Flask): FastAPI مدمج به هذا! يمكن لـ Flask استخدام flasgger أو flask-restx.
• Java (Spring Boot): springdoc-openapi
• .NET: Swashbuckle

مثال مع FastAPI (Python):

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    """
    Create a new item in the database.
    - **name**: The item's name
    - **price**: The item's price in USD
    """
    return item

# This code automatically generates a full OpenAPI spec at /docs or /openapi.json

الإيجابيات:

• دقيق دائمًا: يتم اشتقاق المواصفات مباشرة من الكود قيد التشغيل.
• صيانة منخفضة: قم بتحديث الكود، وتتحدث المواصفات تلقائيًا.

السلبيات:

• يتطلب الوصول إلى الكود: لا يمكنك استخدام هذا لواجهات برمجة التطبيقات التابعة لجهات خارجية أو القديمة التي لا تتحكم فيها.
• يمكن أن يؤدي إلى فوضى في الكود: يمكن أن تجعل التعليقات التوضيحية الموسعة لـ OpenAPI منطق الأعمال أصعب في القراءة.

الطريقة 2: نهج "تحليل حركة المرور"

هذا نهج ذكي "من الخارج إلى الداخل". تقوم بالتقاط حركة مرور HTTP حقيقية بين العملاء وواجهة برمجة التطبيقات الخاصة بك، ثم تقوم بتحليلها لاستنتاج المواصفات.

كيف تعمل؟

تستخدم أداة تعمل كوكيل (proxy) أو أداة اعتراض شبكة (network sniffer). يتم توجيه جميع حركة مرور API عبرها. تقوم الأداة بتحليل الطلبات والاستجابات (عناوين URL، الطرق، الرؤوس، النصوص) وتبني نموذجًا لواجهة برمجة التطبيقات الخاصة بك.

أدوات شائعة:

• Akita Software: تراقب حركة مرور API تلقائيًا لإنشاء ومراقبة المواصفات.
• إنشاء ملف HAR: يمكنك استخدام أدوات المطور في متصفحك (علامة تبويب الشبكة) لتسجيل جلسة مع واجهة برمجة التطبيقات الخاصة بك وتصديرها كملف HAR (أرشيف HTTP). يمكن لبعض الأدوات تحويل هذا إلى OpenAPI.

العملية:

1. قم بتكوين تطبيقك أو عميلك لتوجيه حركة المرور عبر أداة الوكيل.
2. نفّذ مهام سير عمل API الرئيسية (تسجيل الدخول، إنشاء البيانات، جلب البيانات، إلخ).
3. تلاحظ الأداة الأنماط وتولد مواصفات OpenAPI أولية.

الإيجابيات:

• رائع لواجهات برمجة التطبيقات القديمة/الصندوق الأسود: يعمل دون أي تغييرات في الكود أو تعاون من الخادم.
• يعتمد على الاستخدام الحقيقي: يلتقط نقاط النهاية وأشكال البيانات المستخدمة فعليًا.

السلبيات:

• قد يكون غير مكتمل: يولد المواصفات فقط لنقاط النهاية التي قمت باستدعائها أثناء التسجيل.
• قد يفتقد الفروق الدقيقة: قد لا يستنتج بشكل صحيح جميع القيود، أو الحقول الاختيارية، أو استجابات الأخطاء.
• تكلفة الإعداد: يتطلب اعتراض حركة مرور الشبكة، والتي يمكن أن تكون صعبة في بعض البيئات.

الطريقة 3: نهج "جمع الطلبات"

غالبًا ما تكون هذه هي الطريقة الأكثر عملية وفعالية للمطورين والفرق. أنت تستخدم عميل API متقدم لا يرسل الطلبات فحسب، بل يفهم أيضًا تصميم API. تقوم ببناء مجموعة من طلباتك، وتساعدك الأداة على هيكلتها وتصديرها كمواصفات OpenAPI نظيفة.

هذا هو المكان الذي يتفوق فيه Apidog. إنه مبني لسير العمل هذا.

زر

كيف يعمل مع Apidog؟

1. أرسل الطلبات كما تفعل عادةً: لا تغير سير عملك. استخدم Apidog لاختبار وتصحيح نقاط نهاية API الموجودة لديك. عندما ترسل طلبات GET و POST و PUT و DELETE، يلتقط Apidog جميع التفاصيل.

2.  دع Apidog يبني النموذج: خلف الكواليس، أثناء عملك، يبدأ Apidog في فهم هيكل API الخاص بك. يرى نقاط النهاية والمعلمات ونصوص الطلبات ومخططات الاستجابة.

3.   التنظيم في وثيقة: يمكن لـ Apidog تحويل الطلب إلى وثيقة API في الوقت الفعلي. تصبح طلباتك المخصصة صفحة توثيق API منظمة وقابلة للتنقل داخل الأداة. يمكنك إضافة أوصاف وتجميع نقاط النهاية في مجلدات وتنظيف التفاصيل المستنتجة تلقائيًا.

4.   تصدير المواصفات: بمجرد أن تكون مجموعتك دقيقة وموصوفة جيدًا، تقوم بتصديرها. وبعد ذلك يمكن للمستخدمين تصدير مواصفات OpenAPI بتنسيق YAML أو JSON القياسي بنقرة واحدة. هذه المواصفات جاهزة للاستخدام مع Swagger UI، أو الاستيراد إلى أدوات أخرى، أو الالتزام بها في مستودعك.

الإيجابيات:

• سير عمل طبيعي: يتناسب مع كيفية عمل المطورين بالفعل (اختبار واجهات برمجة التطبيقات).
• تحكم عالٍ: تقوم بتنظيم وصقل المواصفات أثناء بناء المجموعة.
• شامل: يمكنك التأكد من توثيق جميع نقاط النهاية، واستجابات الأخطاء، وطرق المصادقة.
• تعاوني: يمكن للفرق العمل معًا على نفس مجموعة الطلبات.

السلبيات:

• يتطلب جهدًا يدويًا: تحتاج إلى التأكد من تغطية جميع نقاط النهاية. إنه ليس تلقائيًا بالكامل من حركة المرور.

الطريقة 4: نهج "الصياغة اليدوية"

في بعض الأحيان، تحتاج إلى بناء المواصفات يدويًا في محرر مثل Swagger Editor أو Stoplight Studio. يتم ذلك غالبًا بالتزامن مع الطرق المذكورة أعلاه.

1. استخدم مجموعة طلباتك كمرجع: اجعل مجموعة Postman أو أوامر cURL أو مشروع Apidog مفتوحًا على شاشة ثانية.
2. بناء المواصفات خطوة بخطوة: لكل نقطة نهاية في مراجعك، قم بترجمتها يدويًا إلى YAML/JSON الخاص بـ OpenAPI. هذا يجبرك على التفكير بعمق في كل معلمة واستجابة.
3. التحقق باستخدام الأمثلة: استخدم معاينة المحرر للتأكد من أن مواصفاتك تتطابق مع سلوك API الفعلي.

الإيجابيات:

• فهم عميق: ستعرف كل تفاصيل مواصفاتك.
• أعلى دقة: يمكنك توثيق الفروق الدقيقة التي قد تفوتها الأدوات الآلية.

السلبيات:

• تستغرق وقتًا طويلاً جدًا: هي الطريقة الأكثر كثافة في العمل.
• عرضة للأخطاء: من السهل ارتكاب أخطاء إملائية أو نسيان نقاط النهاية.

أفضل الممارسات لتوليد مواصفات OpenAPI من الطلبات

بغض النظر عن طريقتك، اتبع هذه المبادئ:

1. ابدأ صغيرًا: اختر نقطة نهاية أساسية واحدة (مثل GET /users). قم بتوليدها أو توثيقها بالكامل، ثم قم بالتوسع.
2. تحقق مبكرًا وبشكل متكرر: استخدم مواصفات OpenAPI لتوليد خادم وهمي على الفور. هل يتصرف مثل API الحقيقي الخاص بك؟ هذا يكشف التناقضات بسرعة.
3. كرر وحسّن: ستكون مواصفاتك الأولى التي تم إنشاؤها تقريبية. تعامل معها كمسودة. أضف الأوصاف والأمثلة وشدد تعريفات المخططات.
4. قم بتضمين استجابات الأخطاء: غالبًا ما يتم تفويت هذا. تأكد من أن مواصفاتك توثق تنسيقات استجابات أخطاء 4xx و 5xx.
5. لا تنسَ المصادقة: وثّق كيفية تأمين واجهة برمجة التطبيقات الخاصة بك (مفتاح API، OAuth2، إلخ) في قسم securitySchemes.

الخاتمة: مخططك ينتظرك

إن توليد مواصفات OpenAPI من الطلبات الموجودة ليس ممكنًا فحسب، بل هو ضرورة عملية لإضفاء النظام على مشاريع API الناضجة. سواء اخترت مكتبة تعتمد على الكود أولاً، أو أداة اعتراض حركة المرور، أو عميل API قوي مثل Apidog، فإنك تستثمر في الوضوح والأتمتة والتعاون.

تعتمد الطريقة التي تختارها على سياقك: التحكم في قاعدة الكود، قيود الوقت، وسير عمل الفريق. ولكن الهدف هو نفسه: تحويل المعرفة الضمنية الموجودة في سجلات طلباتك وأوامر cURL والفهم القبلي إلى عقد صريح يمكن قراءته آليًا ويمكن أن يدفع واجهة برمجة التطبيقات الخاصة بك إلى الأمام.

توقف عن ترك تعقيد واجهة برمجة التطبيقات الخاصة بك يعيش في الظل. ابدأ بالطلبات التي لديك بالفعل، استخدم الأدوات المناسبة، وقم ببناء مخطط OpenAPI الأساسي هذا. سَيَشكرك مستقبلك وكل من يحتاج إلى استخدام واجهة برمجة التطبيقات الخاصة بك.

زر