OpenAPI Specification
OAS 3.1.1 Released!
مواصفات OpenAPI هي مواصفات مفتوحة تعتمد على المجتمع ضمن مبادرة OpenAPI ، وهو مشروع تعاوني Linux Foundation.
تحدد مواصفات OpenAPI (OAS) وصف واجهة مختلطة لبرمجة اللغات لبرمجة HTTP. يتيح ذلك كل من البشر وأجهزة الكمبيوتر اكتشاف وفهم قدرات الخدمة دون الحاجة إلى الوصول إلى التعليمات البرمجية المصدر أو وثائق إضافية أو فحص حركة المرور على الشبكة. عند تحديدها بشكل صحيح عبر OpenAPI ، يمكن للمستهلك فهم وتفاعل الخدمة عن بُعد مع الحد الأدنى من منطق التنفيذ. على غرار ما فعلته أوصاف الواجهة للبرمجة ذات المستوى الأدنى ، تزيل مواصفات OpenAPI التخمين في استدعاء الخدمة.
تتضمن حالات استخدام مستندات تعريف API القابلة للقراءة الآلي ، على سبيل المثال لا الحصر: الوثائق التفاعلية ؛ توليد الكود للوثائق والعملاء والخوادم ؛ وأتمتة حالات الاختبار. تصف مستندات Openapi خدمات API ويتم تمثيلها بتنسيقات YAML أو JSON. يمكن إنتاج هذه المستندات وتقديمها بشكل ثابت أو تم إنشاؤها ديناميكيًا من أي تطبيق.
لا تتطلب مواصفات OpenAPI إعادة كتابة واجهات برمجة التطبيقات الحالية. لا يتطلب ربط أي برنامج للخدمة - قد لا تكون الخدمة الموصوفة مملوكة حتى من قبل منشئ وصفها. ومع ذلك ، فإنه يتطلب وصف قدرات الخدمة في بنية مواصفات OpenAPI. لا يمكن وصف جميع الخدمات بواسطة OpenAPI - لا تهدف هذه المواصفات إلى تغطية كل نمط ممكن من واجهات برمجة تطبيقات HTTP ، ولكنه يشمل دعم واجهات برمجة تطبيقات REST. لا تفرض مواصفات OpenAPI عملية تطوير محددة مثل التصميم الأول أو الكود الأول. إنه يسهل إما التقنية من خلال إنشاء تفاعلات واضحة مع API HTTP.
مشروع GitHub هذا هو نقطة الانطلاق لـ Openapi. ستجد هنا المعلومات التي تحتاجها حول مواصفات OpenAPI ، وأمثلة بسيطة لما يبدو عليه ، وبعض المعلومات العامة المتعلقة بالمشروع.
يحتوي هذا المستودع على مصادر التخفيضات لجميع إصدارات مواصفات OpenAPI المنشورة. للحصول على ملاحظات الإصدار وإصدارات المرشح ، راجع صفحة الإصدارات.
يجب أن يحتوي كل مجلد في هذا المستودع ، مثل المخططات والاختبارات ، على مجلدات تتعلق بالإصدارات الحالية والسابقة من المواصفات.
إذا كنت تريد فقط رؤيتها تعمل ، تحقق من قائمة الأمثلة الحالية.
تبحث لمعرفة كيف يمكنك إنشاء تعريف OpenAPI الخاص بك ، أو تقديمه ، أو استخدامه بطريقة أخرى؟ تحقق من قائمة التطبيقات المتنامية.
تم وصف العملية الحالية لتطوير مواصفات OpenAPI في الإرشادات المساهمة.
يسترشد بتطوير الإصدار التالي من مواصفات OpenAPI من قبل اللجنة التوجيهية التقنية (TSC). تجلب هذه المجموعة من الملتمسين خبرات API الخاصة بهم ، ودمجون ملاحظات من المجتمع ، وتوسيع مجموعة الالتزامات حسب الاقتضاء. سيتم تنفيذ جميع نشاط التنمية في المواصفات المستقبلية كميزات ودمج في هذا الفرع. عند إصدار المواصفات المستقبلية ، سيتم دمج هذا الفرع إلى main .
تعقد TSC مؤتمرات الويب الأسبوعية لمراجعة طلبات السحب المفتوحة ومناقشة المشكلات المفتوحة المتعلقة بمواصفات OpenAPI المتطورة. المشاركة في المكالمات الأسبوعية وجلسات العمل المجدولة مفتوحة للمجتمع. يمكنك عرض تقويم الاجتماع الفني Openapi بالكامل عبر الإنترنت.
تشجع مبادرة Openapi على مشاركة الأفراد والشركات على حد سواء. إذا كنت ترغب في المشاركة في تطور مواصفات OpenAPI ، ففكر في اتخاذ الإجراءات التالية:
لا يمكن استيعاب كل التعليقات ، وقد تكون هناك حجج صلبة أو ضد التغيير المناسب للمواصفات.
انظر: الترخيص (Apache-2.0)
