درس OneOf و anyOf و allOf

إنشاء واجهات برمجة التطبيقات (APIs) التي تتكامل بسلاسة مع الهياكل البيانية المتطورة أمر ضروري في تطوير واجهات برمجة التطبيقات. مخطط JSON، وهو معيار معتمد على نطاق واسع لتعريف واجهات برمجة التطبيقات، يوفر إطار عمل قوي لتعريف الهياكل البيانية وقواعد التحقق بالاشتراك مع OpenAPI.

داخل هذا الإطار، تظهر الكلمات الرئيسية oneOf و anyOf و allOf كأدوات قوية لبناء واجهات برمجة التطبيقات المرنة والقابلة للتكيف. تُساعد oneOf في تحديد مخططات صالحة متعددة لهياكل بيانات واحدة.

تقدم anyOf آلية للتحقق من بنية بيانات مقابل المخططات المتاحة الأخرى. تجمع allOf بين عدة خيارات مخطط في قاعدة تحقق واحدة، مما يضمن أن تلتزم بنية البيانات بجميع القيود المحددة. يساعد Apidog واجهات برمجة التطبيقات على التكيف بسلاسة مع احتياجات البيانات المتنوعة.

ما هي oneOf

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

يمكن أن تحدد كلمة "oneOf" مخططين فرعيين، أحدهما للبالغين وآخر للأطفال. يجب أن يلبي المستند الذي يتم التحقق منه قيود تقتصر على مخطط البالغين أو الأطفال، ولكن ليس كليهما. إليك كيف سيظهر ذلك في مخطط JSON.

{
  "type": "object",
  "oneOf": [
    {
      "properties": {
        "age": { "type": "integer", "minimum": 18 }
              },
      "required": ["age"]
 
   },
    {
      "properties": {
        "age": { "type": "integer", "maximum": 17 }
      },
      "required": ["age"]
    }
  ]
}

في هذا المثال، تُستخدم كلمة "oneOf" لتعريف مخططين فرعيين: واحد للبالغين وآخر للأطفال. يجب أن يلبي المستند الذي يتم التحقق منه قيود مخطط البالغين أو الأطفال، ولكن ليس كليهما. خاصية "age" هي منفذ لتحديد أي مخطط فرعي يجب تطبيقه.

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

ما هي anyOf

تُستخدم كلمة "anyOf" كإحدى البناءات لتعريف مخطط حيث يجب أن تمتثل الحالة المعتمدة لواحد أو أكثر من المخططات الفرعية المحددة. على عكس "oneOf"، التي تفرض اتباعًا حصريًا لمخطط فرعي واحد، فإن "anyOf" توفر مزيدًا من المرونة من خلال السماح للحالة بالامتثال لقيود واحد أو أكثر من المخططات الفرعية المحددة.

دعنا نتخيل سيناريو عملي حيث قد تكون "anyOf" مفيدة. تخيل أنك تعمل مع بيانات JSON تمثل الأفراد، بعضهم بالغون وآخرون طلاب. لكل من البالغين والطلاب خصائص مميزة، وترغب في إنشاء مخطط يستوعب كلا الحالتين.

تمكنك كلمة "anyOf" من التعبير عن هذه المرونة، مما يسمح لوثيقة JSON بأن تكون صالحة إذا كانت تمتثل لمخطط البالغين أو الطلاب. إليك كيف يمثل هذا المثال في مخطط JSON.

{
  "type": "object",
  "anyOf": [
    {
      "properties": {
        "name": { "type": "string" },
        "age": { "type": "integer", "minimum": 18 }
      },
      "required": ["name", "age"]
    },
    {
      "properties": {
        "name": { "type": "string" },
        "grade": { "type": "string", "enum": ["A", "B", "C"] }
      },
      "required": ["name", "grade"]
    }
  ]
}

في هذا المثال، تُستخدم كلمة "anyOf" لتعريف مخططين فرعيين: واحد للبالغين وآخر للطلاب. تُعتبر وثيقة JSON صالحة إذا كانت تلبي قيود مخطط البالغين أو الطلاب. يُتيح هذا تمثيلًا مرنًا للهياكل البيانية المتنوعة ضمن نفس المخطط العام، مما يجعل "anyOf" أداة قوية للتعامل مع سيناريوهات بيانات متنوعة.

oneOf vs anyOf: ما هو الفرق في مخطط Z

في مخطط Z، OneOf وAnyOf يُستخدمان كلاهما لتعريف عدة مخططات، لكنهما يخدمان أغراضًا مختلفة.

OneOf:

OneOf يُستخدم عندما يجب أن يتطابق بالضبط واحد من المخططات المحددة.

يضمن أن تتحقق البيانات ضد واحد فقط من المخططات المحددة.

على سبيل المثال:

{
  "OneOf": [
    {"type": "string"},
    {"type": "number"}
  ]
}

يضمن هذا المخطط أن تكون البيانات إما سلسلة نصية أو رقمًا، ولكن ليس كلاهما.

AnyOf:

AnyOf يُستخدم عندما يمكن أن تتطابق أي واحدة أو أكثر من المخططات المحددة.

يسمح للبيانات بالتحقق ضد مخططات محددة متعددة.

على سبيل المثال:

{
  "AnyOf": [
    {"type": "string"},
    {"type": "number"}
  ]
}

ما هي allOf

تعرف كلمة "allOf" في مخطط JSON مخططًا حيث يجب أن تتوافق الحالة المُعتمدة مع جميع المخططات الفرعية المحددة. بشكل أساسي، تمثل عملية AND المنطقية للمخططات الفرعية. يعني ذلك أن وثيقة JSON التي يتم التحقق منها يجب أن تلبي قيود كل مخطط مدرج تحت "allOf". إليك مثال:

{
  "allOf": [
    {
      "properties": {
        "name": { "type": "string" },
        "age": { "type": "integer", "minimum": 18 }
      },
      "required": ["name", "age"]
    },
    {
      "properties": {
        "hasDegree": { "type": "boolean", "default": true }
      },
      "required": ["hasDegree"]
    }
  ]
}

في هذا المثال، تجمع كلمة "allOf" بين مخططين فرعيين. يحدد المخطط الفرعي الأول خصائص للبالغين، بما في ذلك اسم وعمر مع قيود محددة. يقدم المخطط الفرعي الثاني خاصية للأفراد الحاصلين على درجة، في هذه الحالة، خاصية بوليانية "hasDegree" بقيمة افتراضية True. التأثير المدمج لـ "allOf" هو أنه يجب أن تلتزم وثيقة JSON التي يتم التحقق منها بكل القيود. يجب أن تحتوي على اسم وعمر (مطابق للمخطط الفرعي الأول)، ويجب أيضًا أن تتضمن خاصية "hasDegree" (مطابقة للمخطط الفرعي الثاني).

تكون كلمة "allOf" مفيدة عند إنشاء مخطط يشمل الخصائص والقيود من عدة مخططات فرعية، مما يضمن أن تلبي الحالة المُعتمدة جميع الشروط المحددة. تختلف هذه العملية المنطقية AND عن "anyOf" و "oneOf"، مما يسمح بالمرونة في تلبية واحدة على الأقل أو بالضبط واحدة من المخططات الفرعية المحددة.

ما هو Apidog؟

Apidog هو منصة متعددة الاستخدامات لتكامل واجهات برمجة التطبيقات (APIs) تعمل على تبسيط اختبار واجهات برمجة التطبيقات وتصحيح الأخطاء والتصميم والنمذجة والتوثيق. تقدم واجهة سهلة الاستخدام، وأدوات تعاونية، وميزات لتقييم واجهات برمجة التطبيقات بدقة.

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

مخططات JSON في Apidog مع oneOf و anyOf و allOf

الآن بعد أن عرفت ما هي مخططات JSON وكيف تعمل باستخدام oneOf و anyOf و allOf في هيكلها، سنقوم بتعريفها في Apidog. لإنشاء هذه المخططات بشكل فعال في Apidog، تأكد من تنزيل Apidog في نظامك أو لديك حساب لاستخدام خدمات Apidog عبر الإنترنت.

كيفية إنشاء oneOf

1. إنشاء مشروع جديد في Apidog من نوع HTTP.

2. إنشاء مخطط جديد عن طريق النقر على زر المخطط الجديد.

3. انقر على خيار التوليد من JSON وانتقل إلى خيار مخطط JSON.

4. أدخل الكود التالي في المحرر.

{
  "title": "مثال على مخطط الدفع",
  "type": "object",
  "properties": {
    "payment": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            }
          },
          "required": ["amount", "currency"]
        },
        {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            },
            "cardDetails": {
              "type": "object",
              "properties": {
                "cardNumber": {
                  "type": "string"
                },
                "expirationDate": {
                  "type": "string"
                },
                "cvv": {
                  "type": "string"
                }
              },
              "required": ["cardNumber", "expirationDate", "cvv"]
            }
          },
          "required": ["amount", "currency", "cardDetails"]
        }
      ]
    }
  },
  "required": ["payment"]
}

5. احفظ مخططك.

لقد تم إنشاء مخطط oneOf الخاص بك بنجاح!

كيفية إنشاء anyOf

اتبع جميع الخطوات أعلاه لـ oneOf، ولكن التغيير الوحيد الذي ستجريه لمخطط anyOf الخاص بك هو تغيير الكود. أدخل الكود التالي في المحرر لإنشاء مخططك.

{
  "type": "object",
  "properties": {
    "address": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "street": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "state": {
              "type": "string"
            },
            "zip": {
              "type": "string"
            }
          },
          "required": ["street", "city", "state", "zip"]
        },
        {
          "type": "object",
          "properties": {
            "country": {
              "type": "string"
            }
          },
          "required": ["country"]
        }
      ]
    }
  },
  "required": ["address"]
}

allOf

اتبع جميع الخطوات أعلاه لـ oneOf، ولكن التغيير الوحيد الذي ستجريه لمخطط allOf الخاص بك هو تغيير الكود. أدخل الكود التالي في المحرر لإنشاء مخططك.

{
  "type": "object",
  "properties": {
    "product": {
      "allOf": [
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string"
            }
          },
          "required": ["name", "description"]
        },
        {
          "type": "object",
          "properties": {
            "price": {
              "type": "number"
            },
            "stock": {
              "type": "integer"
            }
          },
          "required": ["price", "stock"]
        }
      ]
    }
  },
  "required": ["product"]
}

فوائد إنشاء المخططات باستخدام Apidog

يمكنك القيام بعدة أشياء مفيدة الآن بعد أن أنشأت مخططات JSON الخاصة بك باستخدام Apidog. بعض الفوائد مذكورة أدناه.

توثيق واجهات برمجة التطبيقات

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

توليد الكود

يمكنك الاستفادة من أدوات مثل قدرات توليد الكود في Apidog لتوليد مكتبات عميل وكود من جانب الخادم تلقائيًا من مخطط JSON الخاص بك. يعمل هذا على تبسيط عملية التطوير ويضمن التناسق بين تعريف واجهة برمجة التطبيقات وتنفيذها.

التحقق من البيانات والتعامل مع الأخطاء

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

اختبار واجهات برمجة التطبيقات

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

تصميم واجهات برمجة التطبيقات

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

خاتمة

في الختام، يمكن أن يؤدي دمج مخططات JSON مع Apidog إلى تعزيز عملية التوثيق لواجهات برمجة التطبيقات بشكل كبير. يوفر مخطط JSON طريقة موحدة لوصف هيكل وقيود بيانات JSON، وعند دمجه مع أدوات توثيق واجهات برمجة التطبيقات، يضمن أن تعكس الوثائق بدقة تنسيقات الطلب والاستجابة المتوقعة.

يدعم Apidog ميزات تستفيد من مخططات JSON. على سبيل المثال، قد يقوم بتوليد الوثائق تلقائيًا استنادًا إلى المخططات المعرفة، مما يسهل الحفاظ على تحديث الوثائق مع تطور واجهة برمجة التطبيقات.