Apicurio-studio: دعم مراجع الكائنات المكونة عبر وثائق المواصفات

حالة الاستخدام

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

الاعتبارات

من أجل دعم المراجع الخارجية ، هناك حاجة إلى عدد من التحسينات. فيما يلي قائمة بدون ترتيب معين:

• يجب تحسين مكتبة نموذج البيانات (حاليًا oai-ts-core ولكن سرعان ما ستصبح apicurio-data-models ) لدعم محلل مرجعي قابل للتوصيل. حاليا هذه المكتبات قادرة على حل المراجع الداخلية فقط. بدلاً من ذلك ، يجب أن يكون مستهلك المكتبة قادرًا على توفير محلل مرجعي مخصص بحيث يمكن حل المراجع الخارجية بنجاح.

• يجب أن يدعم Apicurio Studio مورد نمط "نوع البيانات فقط" ، مع محرر يركز على تصميم أنواع البيانات. يسمح هذا بسير عمل أكثر تحديدًا لإنشاء / إدارة أنواع البيانات بشكل مستقل عن تصميمات API.

• عند تعيين نوع في محرر تصميم واجهة برمجة التطبيقات ، تحتاج الأداة إلى طريقة لتحديد الأنواع من الموارد الخارجية. نحتاج إلى النظر في أفضل السبل لعرض هذه الأنواع الخارجية للمستخدم للاختيار. قد نحتاج إلى طريقة لـ API Designs "لاستيراد" الموارد / الملفات الأخرى بحيث يمكن لواجهة المستخدم تضييق نطاق الخيارات للمستخدم وعرضها بشكل معقول. ضع في اعتبارك أن المحرر سيحتاج إلى جلب أي موارد خارجية وتحليلها من أجل عرض أنواع البيانات المتاحة في نوع من التحكم في واجهة المستخدم للتحديد.

• قد نحتاج إلى تحديد ما إذا كان يمكن استخدام موارد نوع البيانات قيد التقدم كمصدر للمراجع الخارجية في تصميم واجهة برمجة التطبيقات. بمعنى آخر ، هل يمكن الإشارة إلى أنواع بيانات "اللقطة" في تصميم واجهة برمجة التطبيقات؟ أو يجب أن نطلب أن يكون مورد نوع البيانات "نهائيًا" قبل أن يمكن استخدامه كمصدر للمراجع الخارجية. إذا كان الأول ، فلا يمكننا "إنهاء" تصميم واجهة برمجة التطبيقات حتى يتم أيضًا إنهاء تبعياتها. ملاحظة: هذا المفهوم برمته يتطلب منا تنفيذ الموارد النهائية في Apicurio!

• سنحتاج إلى تحديد تنسيق $ ref عند الرجوع إلى موارد Apicurio. في الوقت الحالي ، يحتوي أي تصميم لواجهة برمجة التطبيقات (أو مورد أنواع البيانات النظرية) على معرّف فريد ، لكنه معرّف معتم يتم إنشاؤه عند الإنشاء. هذا المعرّف هو حاليًا الطريقة الفريدة الوحيدة لتحديد مورد لأغراض الحل. بمجرد الانتهاء من أحد الموارد (إذا دعمنا مثل هذا المفهوم) ، فربما يمكننا منح المورد معرفًا أكثر ملاءمةً للإنسان ثم استخدامه في $ ref URI. مهما فعلنا ، تجدر الإشارة إلى أنه عند نشر مورد إلى سجل واجهة برمجة التطبيقات (ميزة مستقبلية أخرى) ، فإن أي مراجع $ في تصميم واجهة برمجة التطبيقات ستحتاج إلى حلها بواسطة سجل واجهة برمجة التطبيقات بطريقة معقولة.

فيما يلي بعض المعلومات حول القيم المسموح بها لـ $ref :

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

يمكن العثور على مزيد من المعلومات حول المراجع في مواصفات OpenAPI و JSON Reference RFC .

هل سيكون من الممكن إعطاء الأولوية لتنفيذ المراجع إلى أنواع البيانات من مواصفات أخرى داخل Apicurio (بدلاً من المراجع الخارجية في البداية)؟

السبب في أنني أقول هذا هو أن بعض وظائف الإسناد الترافقي ضرورية لأي استخدام غير تافه لـ Swagger. على سبيل المثال ، نقوم بتنفيذ العديد من الخدمات التي تشارك أنواع البيانات (مثل العناوين والأشخاص وما إلى ذلك) ونرغب في استخدام Apicurio للحصول على المواصفات لكل هذه. ومع ذلك ، في الوقت الحالي لا يمكننا ذلك بسبب عدم القدرة على استخدام الإسنادات الترافقية.

هل سيكون من الممكن إعطاء الأولوية لتنفيذ المراجع إلى أنواع البيانات من مواصفات أخرى داخل Apicurio (بدلاً من المراجع الخارجية في البداية)؟

السبب في أنني أقول هذا هو أن بعض وظائف الإسناد الترافقي ضرورية لأي استخدام غير تافه لـ Swagger. على سبيل المثال ، نقوم بتنفيذ العديد من الخدمات التي تشارك أنواع البيانات (مثل العناوين والأشخاص وما إلى ذلك) ونرغب في استخدام Apicurio للحصول على المواصفات لكل هذه. ومع ذلك ، في الوقت الحالي لا يمكننا ذلك بسبب عدم القدرة على استخدام الإسنادات الترافقية.

متفق عليه ، هذا من شأنه أن يقودنا إلى منطقة التطبيقات القاتلة.

jsenko يبدو أنه بمجرد الانتهاء من التسجيل الضمني ، لدينا أولوية واضحة من المجتمع. :)

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

أدرك أن هذا قد استغرق بعض الوقت ، ولكن سيتم دعم المراجع الخارجية رسميًا اعتبارًا من Beta 2.46 ، وهو الإصدار التالي (نأمل أن يتم غدًا). توجد واجهة مستخدم جديدة لاستيراد أنواع البيانات والردود من مستندات Apicurio Studio الأخرى إلى المستند الحالي. بالإضافة إلى ذلك ، تم تحديث التحقق لدعم حل http / s الخارجية وكذلك مراجع Apicurio الداخلية. يجب أن تكون هذه خطوة أولى جيدة نحو الدعم الناضج للمراجع عبر الوثائق.