طبقات اللغة

تتبع طبقات اللغة مواصفة Overlay 1.x من مبادرة OpenAPI. تُخزَّن لكل إصدار مواصفة، ولا تُنسخ عند رفع إصدار جديد. هذه الصفحة للتفاصيل. للسبب، راجع المواصفات المترجمة. لخطوات النشر، راجع عرض واجهة برمجة التطبيقات الخاصة بك.

أعلام وأمثلة واجهة سطر الأوامر في README لأداة apidex-cli. هذه الصفحة لا تستبدل ذلك الملف.

مستند الطبقة

كل ملف طبقة YAML أو JSON يتضمن:

• overlay — الإصدار 1.x.y
• info.title — مطلوب
• actions — قائمة غير فارغة
• كل إجراء — target بمسار JSONPath مع update و/أو remove

مثال:

overlay: 1.1.0
info:
  title: Dutch overlay
  version: 1.0.0
actions:
  - target: $.info
    update:
      description: Nederlandse overlay.
  - target: $.paths['/internal']
    remove: true

هدف JSONPath بلا مطابقة يفشل في واجهة الرفع وفي apidex-cli validate. عند القراءة نفس الهدف بلا مطابقة هو لا عملية (لا يغيّر ذلك الإجراء شيئًا؛ وتُطبَّق الإجراءات الأخرى).

لم تعد البوابة تقرأ امتدادات البائع مثل x-description-nl-NL على المواصفة الأساسية. ضع عروض اللغة في ملفات الطبقة.

اللغات المدعومة

en-GB، nl-NL، de-DE، fr-FR، es-ES، se-SE، ar-SA.

الوسم الأساسي وحده (nl) أو اختلاف حالة الأحرف (NL-nl) يُحوَّل إلى الوسم المعياري. تُرفض لغة غير مدعومة عند الكتابة.

القراءة (GET)

اطلب المواصفة مع ?locale= مضبوطًا على لغة البوابة (مثل nl-NL). رأس الاستجابة X-Apidex-Overlay أحد القيم:

القيمة	المعنى
none	لم تُطبَّق طبقة (المواصفة الأساسية، أو بلا لغة مطلوبة)
applied	دُمجت طبقة لتلك اللغة
fallback	توجد طبقة وتعذّر التطبيق؛ الجسم هو المواصفة الأساسية

يتبع التنزيل والتصدير لغة الشاشة، بما في ذلك remove وupdate غير النسخي. لجلب المستند الأساسي، احذف locale.

الكتابة (PUT / DELETE)

PUT /api/specs/{id}/overlays يدرج أو يحدّث اللغات في الحمولة. اللغات المخزّنة لتلك المواصفة غير المذكورة في PUT تبقى كما هي. تُرفض اللغات المعيارية المكررة في حمولة واحدة.

DELETE /api/specs/{id}/overlays يحذف كل طبقات تلك المواصفة.

إصدارات المواصفة الجديدة

الطبقات تتبع معرّف المواصفة. يبدأ إصدار جديد بلا طبقات ما لم ترسل ملفات الطبقة مرة أخرى.

الرفع (البوابة أو upload-spec) يرفض إصدارًا جديدًا يُسقط ترجمات منشورة: بلا ملفات طبقة، أو مجموعة جزئية من اللغات الموجودة في البوابة. التساوي أو المجموعة الأكبر مسموح. --force لا يتجاوز ذلك. المواصفات لأول مرة بلا طبقات تنجح.

apidex-cli validate --require-locales اختياري. هو فحص اكتمال في التكامل المستمر، وليس نفس فحص الإسقاط في البوابة.

الفئات والمواصفات الموروثة

الطبقات ترتبط بـ مواصفة، لا باسم عرض المنتج.

• طبقات الفئة على مواصفة الفئة.
• منتج بـ inheritSpec: true يستخدم مواصفة الفئة (وتلك الطبقات). تُتجاهل الطبقات المعلنة على منتج موروث.
• فحص إسقاط الفئة ينظر إلى مواصفة الفئة، لا إلى منتج واجهة برمجة تطبيقات يشارك اسم الفئة.
• إن فشل PUT للطبقة بعد إنشاء مواصفة فئة، تُحذف تلك المواصفة الجديدة (كما في واجهة البوابة). قد يوسّع الحذف مواصفات منتجات inheritSpec لنفس الفئة؛ أعد تشغيل upload-spec لاستعادة روابط الوراثة.

مواضيع ذات صلة

• المواصفات المترجمة
• عرض واجهة برمجة التطبيقات الخاصة بك
• المرجع — كتالوج واجهات برمجة التطبيقات
• apidex-cli على GitHub