من API أولاً على Swagger إلى عقد فردي على RAML

مرحبًا٪ username٪!

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

ولكن في هذه المقالة ، أود أن أتحدث عن نهج تنفيذ API أولاً ، وهو يختلف نظريًا عما يقدمه Swagger و Apiary. في مقدمة الفكرة مفهوم العقد الواحد وإمكانية تنفيذه على أساس RAML 1.0.

تحت القطع:

• وصف موجز لمبادئ API أولاً ؛
• عقد واحد - إدخال مفهوم ، الشروط المسبقة للمظهر ، والنظر في إمكانية تنفيذه على أساس OAS (Swagger) ؛
• RAML + التعليقات التوضيحية + التراكبات كأساس لعقد واحد ، أمثلة ؛
• مشاكل الرمل ، الخلافات المفاهيمية للمطورين ؛
• فكرة خدمة SaaS استنادًا إلى الفكرة المذكورة أعلاه (الصورة النموذجية أعلاه).

من API أولاً على Swagger إلى عقد فردي على RAML

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

تتطلب نقطة الاتصال هذه تعريفًا رسميًا لا لبس فيه ، وهذا المستند هو أحد مواصفات API. لتطوير وتوثيق مواصفات API اليوم ، يتم استخدام تقنيات ولغات مختلفة ، على سبيل المثال: OAS (Swagger) و Apiary و RAML.

تحدد النقاط الثلاث التالية طبيعة النهج الأول لواجهة برمجة التطبيقات:

1. يجب أن تكون واجهة برمجة التطبيقات (API) أول واجهة عميل للتطبيق المطور ؛
2. بادئ ذي بدء ، يتم تطوير مواصفات API ، ثم جزء البرامج لعملائها ؛
3. يجب أن تتزامن مراحل حياة API مع مراحل حياة توثيقها.

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

عقد واحد. أدوات العقد والمكتبات

لا يدعي مصطلح " العقد المنفرد" أي مشاركة في النقد لاستخدامه في نص المقالة. تطبيقه ، في هذا السياق ، هو شخصيا فكرتي.

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

• مولد التوثيق
• واجهة برمجة تطبيقات الخادم وهمية
• خدمة اختبار الإجهاد
• مكتبة التحقق من الطلب / الاستجابة
• منشئ الكود
• مولد واجهة المستخدم
• الخ.

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

Swagger (OAS) كأداة وصف عقد واحد

تتيح لك القائمة الأكثر شيوعًا في السوق Swagger (OAS) و Apiary (Blueprint) وصف واجهات برمجة تطبيقات HTTP باستخدام لغات خاصة: Open API استنادًا إلى YAML أو JSON ، Blueprint استنادًا إلى Markdown ، مما يجعل المواصفات سهلة القراءة. هناك أيضًا العديد من الأدوات والمكتبات التي تم إنشاؤها بواسطة مجتمع كبير مفتوح المصدر. يتم توزيع Swagger حاليًا على نطاق واسع ، ويمكن القول ، أصبح المعيار الفعلي لواجهة برمجة التطبيقات أولاً. تدعم العديد من الأنظمة الخارجية استيراد مواصفات Swagger ، مثل SoapUI و Readme.io و Apigee ، إلخ. بالإضافة إلى ذلك ، يتيح SaaS Swagger Hub و Apiary الحاليان للمستخدمين إنشاء المشاريع ، وتحميل أو إنشاء مواصفاتهم الخاصة ، واستخدام مولدات الوثائق المدمجة والخوادم الوهمية ، فضلاً عن نشر الروابط للوصول إليها من الخارج.

تبدو Swagger جنبًا إلى جنب مع OAS 3.0 واثقة جدًا ووظائفها لوصف API (خاصة بسيطة) كافية في معظم الحالات. فيما يلي قائمة بمزايا وعيوب Swagger:

الإيجابيات:

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

السلبيات:

• ضعف الدعم النمطي ؛
• عدم وجود أمثلة تم إنشاؤها تلقائيًا لاستجابات الاستعلام استنادًا إلى وصف هياكلها ؛
• غالبًا ما تكون هناك مشكلات تتعلق بالاستقرار الضعيف لمنتجات SmartBear (مؤلفو التبجح) ورد الفعل المتأخر للمطور على ذلك (يستند الرأي فقط إلى تجربة الاستخدام الشخصية وتجربة فريقنا).

لكن القيد الرئيسي الذي لا يسمح باستخدام OAS كوسيلة لوصف العقد الفردي هو عدم القدرة على إرفاق معلومات التعريف المخصصة لوصف المعلمات الإضافية للأدوات / المكتبات المستهدفة.
لذلك ، يجب أن تكون جميع الأدوات التي تعمل على أساس مواصفات Swagger مضمونة بمجموعة من المعلومات التي يمكن أن تستوعب التنسيق الأساسي.

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

في شركتنا ، أثناء تطوير أحد المشاريع (خادم React SPA + API) ، كانت وظيفة الخادم الوهمي التالية مطلوبة:

• تقليد ترقيم الصفحات. يجب ألا يُرجع الخادم قيمًا عشوائية تمامًا للحقول الحالية ، الصفحة التالية ، الصفحات إجمالي الحقول استجابة لطلبات القائمة ، ولكن يجب أن يكون قادرًا على محاكاة السلوك الحقيقي لآلية ترقيم الصفحات مع إنشاء قيم هذه الرموز الأولية اعتمادًا على قيمة الصفحة المستلمة من العميل ؛
• توليد هيئات استجابة تحتوي على مجموعات بيانات مختلفة اعتمادًا على المعلمة المحددة للطلب الوارد ؛
• القدرة على بناء علاقات حقيقية بين الكائنات المزيفة: يجب أن يشير حقل foo_id لكيان Bar إلى كيان Foo الذي تم إنشاؤه سابقًا. يمكن تحقيق ذلك عن طريق إضافة دعم idempotency إلى الخادم الوهمي ؛
• تقليد عمل طرق الترخيص المختلفة: OAuth2 ، JWT ، إلخ.

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

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



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

بعض الأمثلة على الخدمات التي تعمل على مبدأ مماثل:

• SoapUI هو نظام لاختبار واجهات REST & SOAP. يدعم استيراد مشروع من مواصفات Swagger. عند تغيير مواصفات Swagger الأساسية ، يستمر تكوين المشروع استنادًا إلى قائمة مكالمات API في التوازي ويتطلب المزامنة اليدوية ؛
• منتجات SmartBear الأخرى ؛
• Apigee هي خدمة إدارة دورة حياة API. يستخدم مواصفات Swagger كقوالب ، والتي على أساسها تسمح بتهيئة تكويناتها للخدمات الداخلية. لا يوجد أيضًا تزامن تلقائي ؛
• Readme.io هي خدمة تسمح لك بإنشاء وثائق جميلة استنادًا إلى مواصفات Swagger ، ولديها أيضًا آلية لتتبع التغييرات في المواصفات الأساسية وحل التعارضات من خلال تحديث تكوين المشروع من جانب الخدمة. من المؤكد أن هذا يتطلب تعقيدًا غير ضروري لتطوير هذه الخدمة.

يمكنك إضافة العديد من الخدمات الأخرى إلى هذه القائمة التي توفر وظيفة التكامل مع مواصفات Swagger. التكامل بالنسبة لمعظمها يعني النسخ المعتاد للهيكل الأساسي لمواصفات Swagger والإكمال التلقائي اللاحق لحقول التكوين المحلية دون دعم المزامنة مع التغييرات في المواصفات الأساسية.

RAML والشروح والتراكبات

أدت الرغبة في العثور على أداة تستبعد قيود OAS المذكورة سابقًا ، مما يسمح لنا بالنظر في المواصفات كعقد واحد لجميع أدوات العميل ، إلى التعرف على لغة RAML. هناك ما يكفي من الكتابة عن RAML ، يمكنك قراءتها ، على سبيل المثال ، هنا https://www.infoq.com/articles/power-of-raml . حاول مطورو RAML دعم اللغة للوحدات النمطية على مستوى مفهومها. الآن يمكن لكل شركة أو مطور فردي إنشاء قواميسه الخاصة أو استخدام قواميس عامة جاهزة عند تصميم واجهة برمجة التطبيقات ، وإعادة تعريف وتوارث نماذج البيانات الجاهزة. بدءًا من الإصدار 1.0 ، يدعم RAML 5 أنواع مختلفة من الوحدات الخارجية: تشمل ، مكتبة ، ملحق ، سمة ، تراكب ، مما يسمح باستخدام كل منها بمرونة قدر الإمكان اعتمادًا على المهمة.

لقد حان الوقت لمناقشة الإمكانية الرئيسية لـ RAML ، والتي ، لأسباب غير مفهومة تمامًا ، ليس لها نظائر في OAS و Blueprint - الشروح.

التعليقات التوضيحية في RAML هي القدرة على إرفاق بيانات تعريف مخصصة لهياكل اللغة الأساسية.

كانت وظيفة RAML هذه هي السبب في كتابة هذه المقالة.

مثال:

#%RAML 1.0 title: Example API mediaType: application/json # Annotation types block may be placed into external file annotationTypes: validation-rules: description: | Describes strict validation rules for the model properties. Can be used by validation library allowedTargets: [ TypeDeclaration ] type: string[] info-tip: description: | Can be used by Documentation generator for showing tips allowedTargets: [ Method, DocumentationItem, TypeDeclaration ] type: string condition: description: | Named example can be returned if condition is evaluated to true. Can be used by Intelligent mock server allowedTargets: [ Example ] type: string types: Article: type: object properties: id: type: integer title: string paragraphs: Paragraph[] createdAt: type: string (validation-rules): ["regex:/\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d(?:\.\d+)?Z?/"] Paragraph: type: object properties: order: type: integer (validation-rules): ["min:0"] content: string (validation-rules): ["max-length:1024"] /articles/{articleId}: get: (info-tip): This endpoint is deprecated description: Returns Article object by ID responses: 200: body: application/json: type: Article 

يجب أن تحتوي هياكل تعليقات المستخدم التوضيحية نفسها على أوصاف واضحة في RAML. لهذا ، يتم استخدام قسم أنواع التعليقات التوضيحية الخاصة ، ويمكن أيضًا نقل التعريفات إلى الوحدة الخارجية. وبالتالي ، يصبح من الممكن تحديد معلمات خاصة لأداة خارجية في شكل تعليقات توضيحية مرتبطة بالتعريف الأساسي لواجهة برمجة تطبيقات RAML. لتجنب ازدحام المواصفات الأساسية بعدد كبير من التعليقات التوضيحية لمختلف الأدوات الخارجية ، هناك دعم لإمكانية نقلها إلى ملفات منفصلة - تراكبات (وأيضًا امتدادات ) ، مع التصنيف حسب النطاق. إليك ما يقال عن التراكبات في وثائق RAML ( https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#overlays ):

يضيف التراكب أو يلغي عقد تعريف RAML API مع الحفاظ على الجوانب السلوكية والوظيفية. تحدد عقد معينة من تعريف RAML API سلوك واجهة برمجة التطبيقات: مواردها وأساليبها ومعلماتها وأجسامها واستجاباتها وما إلى ذلك. لا يمكن تغيير هذه العقد بتطبيق تراكب. وعلى النقيض من ذلك ، فإن العقد الأخرى ، مثل الأوصاف أو التعليقات التوضيحية ، تعالج المخاوف التي تتجاوز الواجهة الوظيفية ، مثل الوثائق الوصفية الموجهة نحو الإنسان في بعض اللغات ، أو معلومات التنفيذ أو التحقق لاستخدامها في الأدوات الآلية. يمكن تغيير هذه العقد بتطبيق تراكب.

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

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

مثال على البنية الأساسية:

 #%RAML 1.0 title: Phrases API mediaType: application/json types: Phrase: type: object properties: content: string /phrases: get: queryParameters: whoSaid: string responses: 200: body: application/json: type: Phrase 

تراكب:

 #%RAML 1.0 Overlay usage: Applies annotations for Intelligent mock server extends: example_for_article_2_1.raml annotationTypes: condition: description: | Named example can be returned if condition is evaluated to true type: string allowedTargets: Example /phrases: get: responses: 200: body: application/json: examples: firstExample: (condition): $whoSaid is Hamlet content: "To be, or not to be?" secondExample: (condition): $whoSaid is Homer Simpson content: "D'oh!" 

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

تم توضيح المفهوم أعلاه في الشكل أدناه:



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

الحل المحتمل والأكثر وضوحًا هو تطوير محرر خاص أو إضافة لمحرر RAML الحالي عبر الإنترنت https://github.com/mulesoft/api-designer . تظل منطقة التحرير دون تغيير ، ولكن يصبح من الممكن إنشاء علامات تبويب: كل علامة تبويب جديدة هي نافذة لتحرير التراكب المعين لها. عند تعديل الهيكل الأساسي للمواصفات في النافذة الرئيسية ، تتغير أيضًا الهياكل في جميع علامات التبويب التي تم إنشاؤها ، وعندما يتم الكشف عن عدم توافق الهيكل الجديد مع التعليقات التوضيحية الموجودة في تراكبات علامات التبويب ، يظهر تحذير. إن دراسة أكثر تفصيلاً لمثل هذا المحرر هو موضوع منفصل ويستحق دراسة جادة.

التطورات الحالية

في البحث عن حلول موجودة قريبة من تحقيق فكرة استخدام التعليقات التوضيحية كوسيلة لوصف المعلومات الوصفية ، تم العثور على الحلول التالية:

• https://github.com/raml-org/raml-annotations مستودع يحتوي على التعليقات التوضيحية الرسمية المعتمدة من مجتمع مطوري RAML. في الإصدار الحالي ، تتوفر التعليقات التوضيحية لـ OAuth2 فقط. يمكن استخدامها بواسطة الأدوات الخارجية للحصول على معلومات وصفية تصف جوانب تنفيذ OAuth2 لمواصفات API المطورة ؛
• https://github.com/petrochenko-pavel-a/raml-annotations مكتبة التعليقات التوضيحية للمستخدم @ petrochenko-pavel-a مع تجميع منطقي حسب مجال التطبيق. المشروع أكثر تجريبيًا ، ولكنه يوضح تمامًا فكرة استخدام التعليقات التوضيحية. مجموعات التعليقات التوضيحية الأكثر إثارة للاهتمام:
  
  • extraValidation.raml - شروح لوصف قواعد إضافية للتحقق من صحة نماذج المواصفات. يمكن استخدامها ، على سبيل المثال ، من قبل مكتبة الخادم للتحقق من صحة الاستعلامات وفقًا لمواصفات RAML ؛
  • mock.raml - شروح لوصف تفاصيل الخادم الوهمي بناء على مواصفات RAML ؛
  • semanticContext.raml - التعليقات التوضيحية التي تشير إلى السياق الدلالي للكتل الهيكلية الفردية المعلنة لمواصفات RAML ؛
  • structure.raml - شروح توضح دور كيان RAML منفصل في الهيكل العام لنموذج المجال الموصوف ؛
  • uiCore.raml - مثال للتعليقات التوضيحية الممكنة للاستخدام بواسطة أدوات إنشاء واجهة المستخدم استنادًا إلى مواصفات RAML ؛

يحتوي المستودع أيضًا على مكتبات من أنواع الأدوات المساعدة مناسبة للاستخدام كمواد أولية في وصف هياكل البيانات لمواصفات RAML.

مشاكل الرمل

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

• مجتمع مفتوح المصدر صغير ومجزأ ؛
• استراتيجية غير مفهومة لمطور RAML الرئيسي هي mulesoft . تقوم الشركة بتطوير منتجات ليست سوى نسخة من الحلول القائمة على OAS (المدرجة في منصة Anypoint ) ، بدلاً من إنشاء خدمات تؤكد مزايا RAML على Swagger ؛
• نتيجة الفقرة الأولى: عدد صغير من المكتبات / الأدوات مفتوحة المصدر ؛
• عتبة دخول أعلى من OAS (هذا غريب ، لكن الكثير من الناس يعتقدون ذلك) ؛
• نظرًا للعدد الكبير من الأخطاء والمشكلات في UX / UI ، فإن الخدمة الرئيسية غير المناسبة تمامًا وصد المستخدمين هي نقطة الدخول إلى RAML - https://anypoint.mulesoft.com/ .

الخلاف المفاهيمي. الاستنتاج الأول

هناك تناقضات داخل المجتمع فيما يتعلق بالمفهوم الأساسي. يعتقد شخص ما أن RAML هي لغة تعريف نموذجية ، ويعتقد شخص ما أنها لغة تعريف API مثل OAS أو Blueprint (الرجال الذين يطلقون على أنفسهم مطوري RAML غالبًا ما يذكرون ذلك في التعليقات المختلفة). سيسمح مفهوم لغة تعريف النموذج داخل مواصفات RAML لوصف نموذج المجال للمجال دون ربط وثيق بسياق وصف مورد واجهة برمجة التطبيقات ، وبالتالي توسيع آفاق خيارات استخدام المواصفات مع أدوات خارجية (في الواقع ، إنشاء الأساس لوجود هذا العقد الفردي !). فيما يلي تعريف لمفهوم المورد الذي يمكن رؤيته على موقع قراءة المستندات ( http://restful-api-design.readthedocs.io/en/latest/resources.html ، بالمناسبة ، أوصي الجميع بقراءة هذا الدليل الرائع حول تصميم API):

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

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

أعتقد أن هذه هي المشكلة الرئيسية للغة ، والتي سيسمح حلها لـ RAML بتجاوز لغة تعريف واجهة برمجة التطبيقات وتصبح لغة تعريف نموذج كاملة: لغة أكثر عمومية (بدلاً من OAS أو مخطط) تستخدم لوصف العقود الفردية للأنظمة ، والتي هي في الأساس الجوهر الرسمي العديد من مكوناتها.

ما سبق يجعل RAML لاعبًا ضعيفًا غير قادر حاليًا على الفوز في المنافسة ضد Swagger. ربما لهذا السبب ، نتيجة لذلك ، اتخذ المطور الرئيسي لـ RAML تدابير صارمة https://blogs.mulesoft.com/dev/api-dev/open-api-raml-better-together/

فكرة العقد الواحد RAML SaaS

استنادًا إلى مفهوم العقد المنفرد ، بدءًا من فكرة استضافة المواصفات الخاصة بمواصفات Swagger المستندة إلى OAS ، بالإضافة إلى الاعتماد على إمكانية RAML لإعلان المعلومات الوصفية ومشاركة المواصفات الأساسية باستخدام التراكبات ، تقترح فكرة حل SaaS بديل لاستضافة وإدارة المواصفات بناءً على لغة RAML تجاوز Swagger Hub و Apiary في حجم وجودة الوظائف الممكنة.

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


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

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

المكونات الإضافية المحتملة: وثائق واجهة برمجة التطبيقات مع دعم عدد كبير من التعليقات التوضيحية للمعلمات المرنة لعرضها ، خادم وهمية "ذكي" (من المثال أعلاه) ، مكتبات قابلة للتنزيل للتحقق من الطلبات أو إنشاء التعليمات البرمجية ، أدوات التصحيح لطلبات API الصادرة لتطبيقات الهاتف المحمول (وكيل التخزين المؤقت) ، اختبارات التحميل مع إعداد اختبار التدفق من خلال التعليقات التوضيحية ، الإضافات المختلفة للتكامل مع الخدمات الخارجية.

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

الاستنتاج الثاني

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

الموقع الرسمي RAML
قناة سلاك
المواصفات

شكرا لكم على اهتمامكم.