مواصفات OpenAPI

الموسوعة الحرة

مواصفات OpenAPI ( OAS )، المعروفة سابقًا باسم مواصفات Swagger ، هي مواصفات للغة تعريف واجهة قابلة للقراءة آليًا لوصف خدمات الويب وإنتاجها واستهلاكها وعرضها . [ 1 ] طُوّرت في الأصل لدعم إطار عمل Swagger ، ثم أصبحت مشروعًا منفصلاً في عام 2015، تحت إشراف مبادرة OpenAPI، وهي مشروع تعاوني مفتوح المصدر تابع لمؤسسة Linux . [ 2 ] [ 3 ]

يمثل وصف OpenAPI (OAD) [ 4 ] وصفًا رسميًا لواجهة برمجة التطبيقات التي يمكن للأدوات استخدامها لإنشاء التعليمات البرمجية والوثائق وحالات الاختبار والمزيد.

تاريخ

شعار مبادرة OpenAPI، وهي المنظمة التي تقوم بتطوير مواصفات OpenAPI تحت مظلة مؤسسة لينكس.

بدأ تطوير Swagger في أوائل عام 2010 بواسطة توني تام، الذي كان يعمل في شركة Wordnik المتخصصة في القواميس على الإنترنت . [ 5 ]

في مارس 2015، استحوذت شركة SmartBear Software على مواصفات Swagger API مفتوحة المصدر من شركة Reverb Technologies، الشركة الأم لـ Wordnik. [ 6 ]

في نوفمبر 2015، أعلنت شركة سمارت بير عن تبرعها بمواصفات Swagger لمنظمة جديدة تُدعى مبادرة OpenAPI، برعاية مؤسسة لينكس . وشملت الشركات المؤسسة الأخرى: 3scale ، و Apigee ، و Capital One ، وGoogle ، وIBM ، و Intuit ، و Microsoft ، وPayPal ، وRestlet. [ 7 ] [ 8 ]

في 1 يناير 2016، تم تغيير اسم مواصفات Swagger إلى مواصفات OpenAPI (OAS) ونقلها إلى مستودع GitHub جديد . [ 9 ]

توحيد التنسيقات

تم تطوير تقنيتين متشابهتين إلى حد ما، وهما لغة نمذجة واجهة برمجة التطبيقات RESTful من MuleSoft (RAML) ومخطط واجهة برمجة التطبيقات من Apiary، في نفس الوقت تقريبًا الذي كان يُطلق عليه آنذاك اسم مواصفات Swagger.

انضم منتجو كلا الصيغتين لاحقًا إلى مبادرة OpenAPI: Apiary في عام 2016 [ 10 ] وMuleSoft في عام 2017. [ 11 ] وقد أضاف كلاهما دعمًا لـ OAS. [ 12 ] [ 11 ]

سجل الإصدارات

في يوليو 2017، أصدرت مبادرة OpenAPI الإصدار 3.0.0 من مواصفاتها. [ 13 ]

في فبراير 2021، أصدرت مبادرة OpenAPI الإصدار 3.1.0. [ 14 ] تشمل التغييرات الرئيسية في مواصفات OpenAPI 3.1.0 مواءمة مفردات مخطط JSON، وعناصر جديدة من المستوى الأعلى لوصف روابط الويب المسجلة والمدارة خارج النطاق، ودعم تحديد تراخيص واجهة برمجة التطبيقات باستخدام مُعرّف SPDX القياسي، والسماح بالأوصاف إلى جانب استخدام مراجع المخطط، وتغيير لجعل كائن PathItems اختياريًا لتبسيط إنشاء مكتبات مكونات قابلة لإعادة الاستخدام. [ 15 ] [ 16 ] [ 17 ]

في سبتمبر 2025، أصدرت مبادرة OpenAPI الإصدار 3.2.0 من OAS. [ 18 ] تشمل الميزات البارزة الوسوم المهيكلة، ودعمًا من الدرجة الأولى لأنواع وسائط البث، ودعمًا لأساليب HTTP المختلفة، ودلالات أوضح لأمثلة التسلسل، وتحسينات على تدفق بيانات OAuth2 للأجهزة والبيانات الوصفية، وتوضيحًا لقوالب المسارات ودلالات التوجيه. [ 19 ]

مواعيد الإصدار

إصدارتاريخملاحظات [ 20 ]
3.2.02025-09-19إصدار مواصفات OpenAPI 3.2.0
3.1.22025-09-19إصدار تصحيحي لمواصفات OpenAPI 3.1.2
3.1.12024-10-24إصدار تصحيحي لمواصفات OpenAPI 3.1.1
3.1.02021-02-15إصدار مواصفات OpenAPI 3.1.0
3.0.42024-10-24إصدار تصحيحي لمواصفات OpenAPI 3.0.4
3.0.32020-02-20إصدار تصحيحي لمواصفات OpenAPI 3.0.3
3.0.22018-10-08إصدار تصحيحي لمواصفات OpenAPI 3.0.2
3.0.12017-12-06إصدار تصحيحي لمواصفات OpenAPI 3.0.1
3.0.02017-07-26إصدار مواصفات OpenAPI 3.0.0
2.02014-09-08إصدار Swagger 2.0
1.22014-03-14الإصدار الأولي للوثيقة الرسمية
1.12012-08-22إصدار Swagger 1.1
1.010-08-2011الإصدار الأول من مواصفات Swagger

الاستخدام

يصف OAS تنسيق OpenAPI Descriptions (OADs)، [ 4 ] والذي يمكن استخدامه بواسطة مجموعة متنوعة من التطبيقات والمكتبات والأدوات.

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

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

العلاقات بممارسات هندسة البرمجيات

يُطلق على نموذج الاتفاق على عقد واجهة برمجة التطبيقات (API) أولاً، ثم برمجة منطق الأعمال لاحقاً، اسم "التطوير القائم على العقد أولاً"، وذلك على عكس كتابة البرنامج أولاً ثم كتابة وصف لاحق لسلوكه كعقد. وبما أن الواجهة تُحدد قبل كتابة أي كود، يمكن للمطورين اللاحقين محاكاة سلوك الخادم والبدء بالاختبار فوراً. [ 22 ] وبهذا المعنى، يُعد التطوير القائم على العقد أولاً أيضاً ممارسةً لاختبار " التحول إلى اليسار" .

سمات

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

المؤتمرات ومسارات المؤتمرات

رعت مبادرة OpenAPI مؤتمر APIStrat من عام 2017 إلى عام 2019، ثم حولته إلى مؤتمر مواصفات واجهة برمجة التطبيقات (ASC) من عام 2020 إلى عام 2022. [ 23 ] وبدءًا من عام 2023، رعت المبادرة مسارات OpenAPI في العديد من المؤتمرات على مدار العام. [ 24 ]

انظر أيضاً

مراجع

  1. 1 2 "وثائق OpenAPI: البدء" . تعلّم OpenAPI . مبادرة OpenAPI . تم الاطلاع عليه بتاريخ 17 سبتمبر 2024 .
  2. ↑ "مشروع تعاوني جديد لتوسيع مواصفات Swagger لبناء التطبيقات والخدمات المتصلة" . مؤرشف من الأصل في 31 أكتوبر 2023.
  3. ↑ "ميثاق مبادرة OpenAPI" . مبادرة OpenAPI . مؤرشف من الأصل في 26 يناير 2025. تم الاطلاع عليه في 12 نوفمبر 2019 .
  4. 1 2 "وثائق OpenAPI: مسرد المصطلحات" . تعلم OpenAPI . مبادرة OpenAPI. 2023. تم الاطلاع عليه بتاريخ 17 سبتمبر 2024 .
  5. ↑ "انضمام مبتكر Swagger إلى SmartBear" . 28 سبتمبر 2015. تم الاطلاع عليه بتاريخ 6 أغسطس 2019 .
  6. ↑ "شركة سمارت بير تتولى رعاية مشروع Swagger API مفتوح المصدر" . سمارت بير . تم الاطلاع عليه بتاريخ 25 مارس 2015 .
  7. ↑ "الأسئلة الشائعة" . مبادرة OpenAPI . تم الاطلاع عليه بتاريخ 12 نوفمبر 2019 .
  8. ↑ «مشروع تعاوني جديد لتوسيع مواصفات Swagger لبناء التطبيقات والخدمات المتصلة» . linuxfoundation.org . مؤرشف من الأصل بتاريخ 27 أبريل 2016. تم الاطلاع عليه بتاريخ 22 أبريل 2016 .
  9. ↑ مبادرة OpenAPI. "مواصفات OpenAPI" . GitHub . تم الاطلاع عليه بتاريخ 12 نوفمبر 2019 .
  10. ↑ لينسمار، أولي (23 فبراير 2016). "تحديث مبادرة OpenAPI - أعضاء جدد، وتقدم في مواصفات OpenAPI 3.0، والمزيد!" . مبادرة OpenAPI . تم الاطلاع عليه بتاريخ 13 أكتوبر 2014 .
  11. 1 2 أفرام، أبيل (6 مايو 2017). "مجال واجهة برمجة تطبيقات HTTP يتجه نحو التوحيد حول OAS" . InfoQ . تم الاطلاع عليه في 14 مايو 2017 .
  12. ↑ نيسيتريل، جاكوب (18 يناير 2016). "لدينا ثقة بالنفس" . أوراكل أبياري . تم الاسترجاع في 13 أكتوبر 2024 .
  13. ↑ «أعلنت مبادرة واجهات برمجة التطبيقات المفتوحة (OAI) عن مواصفات OpenAPI 3.0.0» . OpenAPIs . 26 يوليو 2017. تم الاطلاع عليه بتاريخ 19 أبريل 2018 .
  14. ↑ "مواصفات OpenAPI 3.1.0 متاحة الآن" . Linux.com . 26 أبريل 2021. تم الاطلاع عليه بتاريخ 26 أبريل 2021 .
  15. ↑ شاربونو، تايلر (7 أبريل 2021). "ما الجديد في OpenAPI 3.1.0؟" . واجهات برمجة تطبيقات نورديك . تم الاطلاع عليه في 7 أبريل 2021 .
  16. ↑ "إصدار مواصفات OpenAPI 3.1.0" . مبادرة OpenAPI . 18 فبراير 2021. تاريخ الاسترجاع: 18 فبراير 2021 .
  17. ↑ ستورجون، فيل (16 فبراير 2021). "الانتقال من OpenAPI 3.0 إلى 3.1.0" . مبادرة OpenAPI . تم الاطلاع عليه بتاريخ 16 فبراير 2021 .
  18. ↑ "الإعلان عن OpenAPI الإصدار 3.2" . مدونة مبادرة OpenAPI . 23 سبتمبر 2025. تم الاطلاع عليه بتاريخ 15 يونيو 2026 .
  19. ↑ "ما الجديد في مواصفات OpenAPI الإصدار 3.2.0؟" . واجهات برمجة تطبيقات نورديك . 27 يناير 2026. تم الاطلاع عليه بتاريخ 15 يونيو 2026 .
  20. ↑ "مواصفات OpenAPI الإصدار 3.2.0" . منشورات مبادرة OpenAPI . تم الاطلاع عليه بتاريخ 15 يونيو 2026 .
  21. ↑ "وثائق OpenAPI: مقدمة" . تعلم OpenAPI . مبادرة OpenAPI. 2023. تم الاطلاع عليه بتاريخ 17 سبتمبر 2024 .
  22. ↑ بريبش، ساشا (2018). تطوير واجهات برمجة التطبيقات: دليل عملي لنجاح تطبيق الأعمال . [بيركلي، كاليفورنيا]: أبريس. ISBN 978-1-4842-4140-0. OCLC 1076234393 . بوجود مستند Swagger (أو أي مستند آخر قابل للقراءة آليًا) متاحًا، يمكن لأعضاء الفريق البدء في العمل على الجزء الخاص بهم من المشروع في نفس الوقت. 
  23. ↑ "تقديم مؤتمر مواصفات واجهة برمجة التطبيقات ASC" . مدونة مبادرة OpenAPI . 8 مايو 2019. تم الاطلاع عليه بتاريخ 15 يونيو 2026 .
  24. ↑ "دعوة لتقديم المقترحات: مسار مبادرة OpenAPI في أيام API بلندن، التاريخ: 13-14 سبتمبر 2023، الموقع: 155 بيشوبسجيت، لندن، المملكة المتحدة" . مدونة مبادرة OpenAPI . تاريخ الاطلاع: 15 يونيو 2026 .

فهرس

  • هاوبت، ف.؛ كاراستويانوفا، د.؛ ليمان، ف.؛ شروث، ب. (2014). منهجية قائمة على النماذج لخدمات متوافقة مع REST . المؤتمر الدولي لخدمات الويب IEEE لعام 2014 (ICWS 2014) . الصفحات 129-136 . doi : 10.1109/ICWS.2014.30 . ISBN  978-1-4799-5054-6.
  • باوتاسو، سيزار (2021). واجهات برمجة التطبيقات الجميلة . لين باب. ص  100.