🧛 🧛🏻 📕 حددها. تقرير ياندكس 🎅 〰️ 🛌🏽

تساعد المواصفات API الجيدة العملاء على استخدامه. قبل بضعة أشهر في Big Pytup ، مطور Yandex Alexander Bryazginbryazginnnقدم عرضًا تقديميًا لما تستند إليه مواصفات REST API كمثال لـ OpenAPI + Swagger ولماذا هناك حاجة إلى هذه الحزمة. من الملخص ، يمكنك معرفة كيف أخطأنا في التوليد التلقائي للمواصفات في الخدمة الجاهزة ، والمكتبات التي كانت مفيدة لنا ونوع الضبط حول مواصفات OpenAPI.

- مرحبا بالجميع ، اسمي ألكسندر. أود أن أتحدث إليكم عن المواصفات.

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

مواصفات REST API

ما هي المواصفات وماذا أعني بهذا في تقريري؟

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

هناك الكثير من اللغات لتحديد المواصفات. هذه هي مواصفات REST و RPC و GraphQL وما إلى ذلك. وسنتحدث اليوم عن مواصفات REST.

Openapi

لنتحدث عن المواصفات باستخدام مثال OpenAPI.

أولاً ، دعنا نفهم ما هو OpenAPI. هذه هي نفس اللغة لوصف المواصفات. وهو في حد ذاته ملف - بتنسيق YAML أو JSON أو XML ، ممن يعجبهم أكثر - مع وصف للواجهة ونقاط النهاية والمخططات.

اختيال

عندما نتحدث عن OpenAPI ، لا يمكننا أن نقول عن Swagger.

Swagger هو في الأساس واجهة مستخدم OpenAPI تسمح لك بتصور مواصفاتك بشكل جميل.

في Swagger ، كما هو الحال في OpenAPI ، يوجد وصف لنقاط النهاية الموجودة في المواصفات الخاصة بك.

يوجد وصف للتفويض في API الخاص بك.

يوجد وصف للنماذج أو الدوائر التي تتعامل معها في API الخاص بك - على سبيل المثال ، قم بقبولها للإدخال أو إعادتها للإخراج.

يوجد وصف للأمثلة والطلبات والاستجابات المتوقعة من API الخاص بك.

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

^{_{رابط من الشريحة}}

مع كل هذا ، يمكنك اللعب على منصة اختبار أعدها فريق Swagger. هذا هو petstore.swagger.io. هناك مثال لمواصفات أثارها Swagger. يمكنك الذهاب إلى الخلفية الحقيقية واللمس. نوصي.

لذا نقول: OpenAPI، Swagger، specification. ولكن لماذا كل هذا مطلوب لشخص يكتب ، على سبيل المثال ، الخلفية؟

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

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

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

كيف نعد OpenAPI

قررنا لماذا نحتاج كل هذا. لنتحدث عن كيف أفسدنا جيل المواصفات في خدمتنا. أولاً ، سياق صغير.

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

وكانت الواجهة الخلفية فجأة في بيثون. استخدمنا Falcon كإطار عمل ، و marshmallow كأداة للتسلسل وإلغاء التسلسل ، و webargs كأداة للتحقق.

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

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

أي أننا سنصف العديد من المخططات على Marshmallow. علاوة على ذلك ، سنقوم بإعداد بعض الأقلام من أجل ، على سبيل المثال ، للتسجيل وتلقي المفضلة لدينا.

وفي الواقع ، سيصفون التطبيق نفسه ، والذي سيثير نقطة النهاية لإنشاء واستقبال الحيوانات الأليفة.

هكذا ستبدو معًا. خدمة بسيطة إلى حد ما.

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

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

لذلك ، وصلنا إلى استنتاج أننا نريد إنشاء تكوين OpenAPI. نظرًا لمجموعتنا التكنولوجية ، وجدنا مكتبة مثل apispec . Apispec هي مكتبة من الشركات المصنعة ، أي مؤلفو Marshmallow و Webargs. يشكلون معًا نظامًا بيئيًا كبيرًا.

دعونا نرى كيف يمكنك استخدام apispec على مكدسنا لتعليمها كيفية إنشاء مواصفات لنا.

كان لدينا مورد ومعالج محدد لطريقة الحصول على هذا المورد. لديه نوع من الجسد.

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

باستخدام مثال طلب ما بعد ، نصف: بالإضافة إلى حقيقة أن هناك استجابة 201 نعيد فيها Pet ، هناك أيضًا النص المتوقع للطلب الذي يأتي إلينا. وداخل هذا الطلب ، نتوقع JSON ، ونتوقع أن يكون JSON بتنسيق Pet.

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

دعونا نرى ما تم إنشاؤه لهذا التطبيق الضخم في هذا الملف.

بادئ ذي بدء ، في هذا الملف سيكون هناك وصف للإصدار الذي تم إنشاء المواصفات فيه. هذا أمر مهم بحيث يفهم كل من يفسر هذه المواصفات التنسيق المطلوب تفسيره. تختلف المواصفات من إصدار لآخر.

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

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

بالإضافة إلى المخططات ، ينمو وصف نقاط النهاية نفسها هناك. في هذه الحالة ، وصف كل طريقة براعم.

باستخدام طريقة get ، نحصل على وصف لما نقوم به باستخدام طريقة get.

وبالضبط الوصف الذي وضعناه في مستندات نقطة النهاية المقابلة التي تم نشرها على المنشور. أي أننا تلقينا بالفعل نوعًا من الملفات.

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

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

أرداف

ثم نصل إلى المرحلة التالية ، حيث سنتحدث عن مجموعة أدوات مفيدة حول المواصفات باستخدام مثال OpenAPI.

^{_{رابط من الشريحة}}

الأداة الأولى التي أود الحديث عنها هي Swagger-UI. بعد ذلك ، سأوفر روابط إما لمورد ويب حيث يمكنك كزة الأداة المقابلة ، في هذه الحالة SwaggerHub ، أو إلى الأمر لتشغيل المستند المقابل باستخدام Docker.

كلنا نحب Docker كثيرًا. يساعدك Docker في عدم وضع JavaScript أو أي Java على المستوى المحلي. فقط خذه ، قم بتشغيله بأمر واحد ، وكل شيء يناسبك.

لذا ، فإن Swagger-UI هي في الواقع أداة تسمح لك بعرض مواصفاتك بشكل جميل. كما قلت سابقًا ، يتم تشغيلها محليًا باستخدام Docker ، ربما Swagger.

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

^{_{رابط من الشريحة}}

بالإضافة إلى Swagger-UI ، هناك أداة ملائمة لـ Swagger-editor. يمكنك استخدامه على الويب ، يمكنك التقاطه في مكان محلي أو على أي آلة كاتبة. يسمح لك بتغيير المواصفات في الوقت الحقيقي ومشاهدة عرضها هنا. أي أنها أداة مريحة للغاية في مرحلة تصميم واجهة برمجة التطبيقات ، على سبيل المثال ، عندما لا يكون لديك مواصفات تم إنشاؤها ، وتريد مزحة أو وصف الخلفية الخاصة بك بطريقة أو بأخرى دون وجود خلفية حقيقية أو تم إنشاؤها خلفك.

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

هذا ، في هذه الحالة ، نرى إطلاق Prism على رأس المواصفات ، التي سرقتها من متجر Swagger. نرى أن Prism وجد جميع نقاط النهاية المحددة في المواصفات ، وقالوا إنها تزعجهم بصدق.

دعونا نحاول أن نشعر بما يمكن أن يفعله المنشور.

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

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

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

السمة السحرية هي الحالة. في الواقع ، يتم تقديمه وفقًا لمواصفات ENUM. إذا قمنا بتحويل حالة غير مدرجة في هذا ENUM ، فسنحصل على أربع نقاط.

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

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

في هذه الحالة ، نعلن عن رمز معين ، على سبيل المثال ، الرمز 400 أو 422 ، لأي شخص كما تريد. أي أنه مع إدخال صالح ، لا يوجد دائمًا مخرج صالح. لذلك ، في المواصفات ، نصف خيارات الإجابة المختلفة. ويمكننا أن نقول بوضوح عند اهتزاز القلم Prism: هذه المرة أنا في انتظار أن تجيبني ، على سبيل المثال ، الخطأ 404. لنفترض أن هذه هي الحالة عندما أسحب المقبض بمعرف ، ولكن لا يوجد مثل هذا المعرّف.

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

بالإضافة إلى التحقق من صحة الطلب ، سيتم إنشاء ردود. في أبسط الحالات ، كما قلت ، يولد إجابات بالقدوة. هناك خيار ثانٍ - عندما تطلبه صراحةً: يُرجى إنشاء إجابات ديناميكية. تعني الإستراتيجية الديناميكية أنها ، اعتمادًا على النوع ، على سبيل المثال ، int ، ستولد الآلاف أو المليارات أو أي شيء آخر. أو للسلسلة ، تجزئة غريبة وغير مفهومة.

أيضًا ، عندما قلت في الجولة الأولى أنه يمكنك إنشاء البيانات ، سألنا أنفسنا: سيكون من الرائع أن يتكامل Prism مع faker. ربما يعرف أولئك الذين استخدموا بايكر بايكر كم هو رائع عندما تريد قفل بعض البيانات أو محاكاة البيانات في قاعدة البيانات.

لذا ، المنشور مكتوب في JavaScript. تحتوي JavaScript أيضًا على Faker.js ، ولدى Prism تكامل تلقائي مع faker. يمكنك تحديد صراحة في مواصفاتك أنواع البيانات الزائفة التي سيعطيها قلمك. وهذا يعني أن OpenAPI يدعم نظام المكونات الإضافية الذي يسمح لك بتوسيع المواصفات الخاصة بك بحيث لا يهتم OpenAPI والمحلل نفسه. ولكن إذا كانت هناك مكونات إضافية تحلل مواصفاتك ، فيمكنها استخدام بعض الحقول الإضافية.

لذا ، يقدم لك Prism استخدام حقل المكون الإضافي X-faker الاختياري. مريح للغاية.

هنا ، تحت العلامة النجمية ، أشرت إلى أنه يمكن وصف الاسترجاعات في OpenAPI. هذا هو نظام التفاعل عندما تقوم بتسجيل رد الاتصال على قلم معين وانتظر ذلك بعد ذلك سوف تتلقى رد اتصال محدد على عنوان url الذي قمت بتسجيله. لذا ، بريزم وهي تعرف كيف تبتل.

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

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

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

لذا ، يمكنك القدوم وقول بريزم: هذه المرة أريد مثالًا محددًا ، وفي المرة القادمة أريد مثالًا آخر.

^{_{تحدث الارتباط من الشريحة}}

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

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

نمر من Postman أبعد من ذلك. تحدثنا عن Prism ، ولها وظيفة - التحقق من صحة الاستعلام. في الواقع ، هناك أداة منفصلة تسمح لك بامتصاص الخلفية الخلفية التي تعمل بلا رحمة ومعرفة ما إذا كانت تعمل حقًا وفقًا للمواصفات.

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

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

^{_{رابط من الشريحة}}

التالية أريد التحدث بمزيد من التفاصيل حول أداة من Swagger نفسها مثل Swagger-codegen. في الواقع ، إنه يشبه السكين السويسري. بادئ ذي بدء ، أي نوع من الأفكار كان لدى الرجال عندما كتبوا هذه الأداة.

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

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

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

لذلك ، بالإضافة إلى العميل في Python ، قام بإنشاء اثنين من المستندات واختبار المجلدات السحرية. سنتحدث عنها لاحقًا بمزيد من التفاصيل. والكثير من السكر حتى تتمكن من لف هذا العميل في مكتبة جاهزة. هناك gitignore ، هناك ملفات CI ، دعنا نقول لترافيس ، هناك سكر للبوابة. هناك متطلبات ، setup.py و tox.ini. أي أن كل ما يساعدك ببساطة على أخذ هذا العميل والالتزام به وإرساله موجود بالفعل في شكل مكتبة يمكن إعادة استخدامها.

دعونا نلقي نظرة فاحصة على ما ولده في العميل.

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

بالإضافة إلى النموذج ، ظهرت أيضًا كيانات مثل PetApi - فهذه مجرد أغلفة عميل فوق مجموعة نقاط النهاية ، والتي تجمعها OpenAPI إما عن طريق العلامات أو عن طريق نقاط النهاية.

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

ما الذي يتم تنفيذه من هذا العميل الذي تم إنشاؤه؟ من المثير للاهتمام - النهج التعاقدي. لنتحدث عنه أكثر.

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

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

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

لذا ، فإن Swagger-codegen يولد عملاء ونماذج وفقًا لمنهج العقد. يسمح لك بالقول في الوقت الفعلي: نعم ، أريد أن يقوم العميل في وقت التشغيل بالتحقق من جميع البيانات للتأكد من امتثالها للعقود. وإذا لم يتم الوفاء بالعقد ، فسيقول ذلك على الفور.

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

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

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

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

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

يمكنك أيضًا تكوين هؤلاء العملاء وكتابة استيراد النماذج الخاصة بك ، بدلاً من تلك التي تم إنشاؤها بواسطة Swagger-codegen.

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

من بين أمور أخرى ، يسمح لك بإنشاء وثائق بتنسيق HTML و Confluence إذا كان شخص ما يستخدمه. الأمثلة التي أردت عرضها لـ OpenAPI انتهت أيضًا هناك.

^{_{كل هذه الأدوات متاحة على الرابطين أدناه على الشريحة: openapi.tools وgithub.com/APIs-guru/awesome-openapi3}}

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

من المهم هنا هو محول من مواصفات إلى أخرى. أي أنه يمكنك إنشاء Blueprint API أو أي شيء تريده من مواصفات OpenAPI والعكس صحيح. توجد مكتبة وهمية للتوثيق. أي أن كل ما تحدثت عنه سينعكس في هذه المجموعات.

هناك رابط يمكنك اتباعه أيضًا. تأكد من البحث.

^{_{رابط من الشريحة}}

إلى جانب الأدوات حول OpenAPI ، هناك أدوات حول Swagger. هناك SwaggerHub و Swagger Inspector. يتم تمييزها باللون الأزرق لأنها مجموعة أدوات على الويب. يمكنك الذهاب إلى هناك مباشرة وكخدمة تستخدم SwaggerHub و Swagger Inspector ، وهما في الواقع تراكب للمكتبات التالية: Swagger-editor و Swagger-codegen و Swagger-UI. كل ما ناقشناه للتو.

جميع المكتبات صفراء ، وهي مفتوحة المصدر ، كما رأينا. يوجد على GitHub ، على شكل Docker. استعمال.

استنتاج

ماذا ناقشنا اليوم؟ مواصفات REST API باستخدام OpenAPI و Swagger كأمثلة. أريد أن أؤكد أن OpenAPI هو مجرد طريقة واحدة لوصف المواصفات. كثير منهم. من بين المثير للاهتمام ، انظر أيضًا Blueprint API. ربما شخص آخر سيحب شيئا.

شاهدنا أيضا Swagger. في الجوهر ، هذا ، كما قلنا بالفعل ، هو مجرد واجهة مستخدم جميلة حول المواصفات ، والتي تسمح لك بالنظر إليها واستكشافها بطريقة ملائمة. في الواقع ، هذه الأدوات كثيرة أيضًا ، بدءًا من ReDoc و Sphinx المشهورين ، وتنتهي في الواقع Markdown. أي أنه يمكنك إنشاء Markdown من OpenAPI ، وسيتم عرضها بشكل جميل في كل GitHub و GitLab - أينما تريد.

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

^{_{روابط من الشريحة: FastAPI ، SAFRS ، rororo}}

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

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

وأخيرًا ، ناقشنا نوع الأداة المساعدة حول المواصفات باستخدام أمثلة OpenAPI و Swagger. لجميع النقاط I جعل الروابط، تبدو على وجه اليقين، وهناك الكثير من الأمور المثيرة للاهتمام:

- OpenAPI / التبختر
swagger.io/docs/specification/about

- مثال على الصقر + الخطمي + apispec
github.com/marshmallow-code/apispec
github.com/tiangolo/fastapi

- OpenAPI / التبختر
الكعك
openapi.tools swagger.io/tools swagger.io/tools/open-source/open-source-integrations github.com/APIs-guru/awesome-openapi3

ماذا لدي كانت رسالة التقرير؟ يا رفاق ، كتابة المواصفات ليست نوعًا من البيروقراطية. وهذا ليس صعبًا كما قد يبدو للوهلة الأولى ، ولكنه بسيط ويوفر العديد من الأدوات المفيدة ، يفتح لك فرصًا رائعة.

اكتب المواصفات. نوصي. شكرا جزيلا لك.

جميع الرموز والروابط متوفرة في العرض التقديمي .