مقدمة
كان الفريق الذي اتخذت فيه خطواتي الأولى في مجال كتابة التعليمات البرمجية الصناعية يقوم بتطوير واجهة برمجة تطبيقات ملائمة لوظائف منتج البرنامج في C # (للراحة ، دعنا نسميها ، على سبيل المثال ، الحرف E) ، الذي كان موجودًا لسنوات عديدة وأقام نفسه في السوق على جانب إيجابي للغاية . وهنا ، على ما يبدو ، لا ينبغي أن يكون لدى Padawan الشاب أي أسئلة حتى الآن ، ولكن تخيل أنك في وقت سابق ، على الأرجح ، كتبت واجهات برمجة التطبيقات الخاصة بك على الويب ، لكن من غير المحتمل لجمهور عريض ، مما يعني أنك عشت على مبدأ "لقد خلقتها بنفسي - أنا أستخدمها "، وإذا كان شخص ما مهتمًا بوظيفة واجهة برمجة التطبيقات ، فمن المحتمل أن تكون قد ألقت به ملف pdf مع تعليمات مفصلة (على الأقل كنت سأفعل ذلك). "أين يمكنني رؤية واجهة التطبيق الوظيفية" - سألت قائد الفريق ، متوقعًا الحصول على رابط إلى مستند نصي. أجاب: "ألقِ نظرة على Swagger".
انتظر ، كيف يتم تشغيل المنتج بنجاح لفترة طويلة ، وواجهة برمجة التطبيقات التي تكتبها إليه الآن فقط؟
هذا صحيح ، حتى وقت قريب ، لم يكن لدى E واجهة برمجة تطبيقات عامة ملائمة. في الواقع ، تم إنجاز كل العمل من خلال واجهة الويب ، وتألفت الخلفية من العديد من الخدمات المصغرة الداخلية ، والتي كان من المستحيل دمجها من الخارج دون فهم واضح لمنطق العمل الداخلي ، ناهيك عن حقيقة أنها تتألف من نسبة كبيرة من الإرث. كان من الضروري الانتباه إلى العملاء الذين يرغبون في التفاعل مباشرة مع الخادم ، مما يعني تزويدهم بواجهة برمجة تطبيقات جميلة ومريحة. ما هو المطلوب لهذا؟ كل ما تمت كتابته سابقًا هو اتخاذ وتأسيس العمل مع جميع الخدمات الداخلية الصغيرة بأنفسنا ، بالإضافة إلى توفير وثائق مريحة وجميلة ، مما يجعلها جميلة ومفهومة ، والأهم من ذلك أنها ناجحة تجاريًا.
حسنًا ، ما هو اختيال وما هي فائدته للعالم؟
في الجوهر ، Swagger هو إطار لمواصفات RESTful API. يكمن سحره في حقيقة أنه يجعل من الممكن ليس فقط عرض المواصفات بشكل تفاعلي ، ولكن أيضًا إرسال الطلبات - ما يسمى Swagger UI ، هكذا تبدو:
كما نرى - وصف كامل للطرق ، بما في ذلك النماذج ، رموز الاستجابة ، معلمات الاستعلام - بشكل عام ، بشكل واضح.
وكيف يعمل؟
دليل كبير لتطبيق Swagger في ASP.NET Core
من الصفر هنا في
هذه المقالة.
الفكرة هي تكوين العرض باستخدام تعليقات توضيحية خاصة لطرق API ، فيما يلي مثال:
اختيال codegen
إذا كنت ترغب حقًا في ذلك ، يمكنك إنشاء عميل أو خادم مباشرةً وفقًا لمواصفات Swagger API ، لذلك تحتاج إلى منشئ رموز Swagger-Codegen. أعتقد أن الوصف الوارد في الوثائق لا يحتاج إلى شرح:
هذا هو مشروع Swagger Codegen ، والذي يسمح بإنشاء مكتبات عملاء API (إنشاء SDK) ، وعقبات الخادم والوثائق المعطاة تلقائيًا لمواصفات OpenAPI. حاليًا ، يتم دعم اللغات / الأطر التالية:
- عملاء واجهة برمجة التطبيقات: ActionScript ، Ada ، Apex ، Bash ، C # (.net 2.0 ، 3.5 أو الأحدث) ، C ++ (cpprest ، Qt5 ، Tizen) ، Clojure ، Dart ، Elixir ، Elm ، Eiffel ، Erlang ، Go ، Groovy ، Haskell (http -عميل ، خادم) ، Java (Jersey1.x ، Jersey2.x ، OkHttp ، Retrofit1.x ، Retrofit2.x ، Feign ، RestTemplate ، RESTEasy ، Vertx ، Google Client Library Library for Java، Rest-assured)، Kotlin، Lua، Node.js (ES5 ، ES6 ، AngularJS مع التعليقات التوضيحية لبرنامج التحويل البرمجي من Google) الهدف- C ، Perl ، PHP ، PowerShell ، Python ، R ، Ruby ، Rust (الصدأ ، خادم rust) ، Scala (akka ، http4s ، swagger-async- httpclient) ، Swift (2.x ، 3.x ، 4.x) ، Typescript (Angular1.x، Angular2.x، Fetch، jQuery، Node)
- دعامات الخادم: Ada و C # (ASP.NET Core و NancyFx) و C ++ (Pistache، Restbed) و Erlang و Go و Haskell (خادم) وجافا (MSF4J و Spring و Undertow و JAX-RS: CDI و CXF و Inflector و RestEasy ، Play Framework ، PKMST) ، Kotlin ، PHP (Lumen ، Slim ، Silex ، Symfony ، Zend Expressive) ، Python (Flask) ، NodeJS ، Ruby (Sinatra ، Rails5) ، Rust (rust-server) ، Scala (Finch ، Lagom ، سكالاترا)
- مولدات وثائق واجهة برمجة التطبيقات: HTML، Confluence Wiki
- ملفات التكوين: Apache2
- آخرون: jmeter
المعلومات الأخرى ، وخاصة تعليمات الاستخدام ، معروضة هنا:
معلومات عامةوهنا:
التفاصيلالخاتمة
كانت هذه نظرة عامة موجزة مرئية لمطوري واجهة برمجة التطبيقات للمبتدئين ، وكان هدفهم تقديم نظرة عامة حول ماهية Swagger ، ولماذا كانت هناك حاجة إليها ، وما الذي يوفره المزايا الرئيسية من وجهة نظري الشخصية.