لماذا تعد "extraProperties" هي الطريقة لتمثيل Dictionary/Map في Swagger/OpenAPI 2.0




hash mapping (2)

على الرغم من أنني رأيت الأمثلة في المواصفات OpenAPI :

type: object
additionalProperties:
  $ref: '#/definitions/ComplexModel'

ليس من الواضح بالنسبة لي السبب في أن استخدام additionalProperties هو المخطط الصحيح لخريطة / قاموس.

كما أنه لا يساعد في أن الشيء الملموس الوحيد الذي يجب على المواصفات أن تقوله حول الخصائص additionalProperties هو:

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

  • العناصر
  • كل
  • الخصائص
  • additionalProperties

أول شيء ، لقد وجدت تفسيراً أفضل لخصائص additionalProperties :

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

حتى هنا كيف فهمت أخيرا هذا:

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

سوف تتطابق الخصائص additionalProperties مع أي اسم خاصية (سيكون بمثابة مفتاح dict ، وسيكون $ref أو type هو مخطط قيمة dict ، وبما أنه يجب ألا يكون هناك أكثر من خاصية بنفس الاسم لكل كائن معين ، وسوف نحصل على إنفاذ مفاتيح فريدة من نوعها.

لاحظ أنه على عكس dict Python الذي يقبل أي قيمة ثابتة كمفتاح ، نظرًا لأن المفاتيح الموجودة هنا في أسماء خصائص جوهرية ، يجب أن تكون سلاسل. (شكرا تيد إبشتاين لهذا التوضيح). يمكن تتبع هذا القيد إلى pair := string : value في مواصفات json .


تشن ، وأعتقد أن إجابتك صحيحة.

بعض الخلفية الإضافية التي قد تكون مفيدة:

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

يستخدم مخطط JSON الكلمة الأساسية properties للتحقق من صحة أزواج قيمة الاسم المعروفة مسبقًا ؛ ويستخدم patternProperties (أو patternProperties ، غير معتمد في OpenAPI 2.0) للتحقق من صحة الخصائص غير المعروفة.

للتوضيح:

  • يجب أن تكون أسماء الخصائص ، أو "المفاتيح" في الخريطة ، سلاسل. لا يمكن أن تكون أرقامًا أو أي قيمة أخرى.
  • كما قلت ، يجب أن تكون أسماء الممتلكات فريدة من نوعها. لسوء الحظ ، لا تتطلب مواصفات JSON التفرد بشكل صارم ، ولكن ينصح التفرد ، ويتوقع من قبل معظم تطبيقات JSON. المزيد من الخلفية here .
  • properties additionalProperties يمكن استخدامها وحدها أو مجتمعة. عند استخدام extraProperties بمفرده ، بدون خصائص ، يعمل الكائن بشكل أساسي map<string, T> حيث T هو النوع الموصوف في المخطط الفرعي extraProperties. ربما هذا يساعد على الإجابة على سؤالك الأصلي.
  • عند تقييم كائن مقابل مخطط واحد ، إذا كان اسم الخاصية يطابق أحد تلك properties المحددة في properties ، فلابد أن تكون قيمتها صالحة فقط مقابل المخطط الفرعي المقدم لتلك الخاصية. سيتم استخدام المخطط الفرعي additionalProperties للعقارات ، إذا تم توفيره ، فقط للتحقق من صحة الخصائص التي لم يتم تضمينها في خريطة properties .
  • هناك بعض القيود على extraProperties كما هو مطبق في مكتبات Java Swagger الأساسية. لقد وثقت هذه القيود here .






openapi