دليل OpenAPI 3.0: تعريف مواصفة OpenAPI

هل تحتاج إلى مساعدة في تطوير وتوثيق الـ APIs لمشاريع كبيرة أو معقدة؟ لا داعي للقلق! لدينا الحل المناسب لك - مواصفة OpenAPI (المعروفة سابقًا باسم Swagger Specification). هذا المعيار المجاني ومفتوح المصدر يجعل تطوير وتوثيق الـ API عملية سهلة للغاية! مع OpenAPI، يمكنك بسهولة إنشاء وتوثيق الـ APIs باستخدام تنسيق موحد يسهل فهمه.

وفر الوقت الذي تقضيه في محاولة فهم تطوير وتوثيق الـ API المعقدة. دعنا نساعدك في تبسيط العملية باستخدام OpenAPI!

ما هي مواصفة OpenAPI (OAS)

OpenAPI هي مواصفة تحدد هيكل الـ RESTful API وتصف قدراتها. توفر مواصفة OpenAPI طريقة قياسية لتوثيق والتفاعل مع الـ APIs، مما يسمح للمطورين باكتشاف وفهم كيف تعمل بكفاءة. تستخدم الـ RESTful APIs بروتوكول HTTP لنقل البيانات، مما يسهل كتابة الأنظمة والمنصات بلغات برمجة مختلفة للتواصل مع بعضها البعض.

مع OpenAPI، لست بحاجة إلى الوصول إلى كود المصدر أو فحص حركة الشبكة لفهم كيفية عمل الـ API. توفر تعريف الـ API نفسه جميع المعلومات التي تحتاجها.

تنسيق OpenAPI

أحدث إصدار من OpenAPI هو 3.0. يمكن كتابة تعريفات OpenAPI بتنسيق JSON أو YAML. يمثل JSON البيانات باستخدام أزواج مفتاح-قيمة بدلاً من كتابة وصف طويل للـ API واتباع هيكل OpenAPI. يجعل ذلك من السهل فهم قدرات الـ API، حتى لو كنت لا تملك الوصول إلى كود المصدر أو الوثائق.

مثال على مواصفة OpenAPI 3.0 بتنسيق JSON:

{
  "openapi": "3.0.0",
  "info": {
    "title": "عنوان ال API",
    "description": "وصف ال API",
    "version": "1.0.0"
  }
}
}

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

بينما يعد JSON هو التنسيق القياسي لـ OpenAPI، يمكنك أيضًا استخدام YAML، وهي لغة ترميز أكثر بساطة. تجعل من السهل إنشاء وتحرير مستندات OpenAPI.

openapi: 3.0.0
info:
  title: عنوان ال API
 
 description: وصف ال API
  version: 1.0.0

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

تستخدم مواصفة OpenAPI أنواع بيانات JSON المعرفة في مواصفة JSON Schema. تشمل هذه الأنواع البيانات الأعداد الصحيحة، والأرقام، والقيم المنطقية، والسلاسل. يمكنك أيضًا تعديل تنسيق هذه الأنواع باستخدام خاصية 'format'، مثل int32، int64، float، double، binary، data، date-time، وpassword format. كما يسمح OpenAPI باستخدام نماذج (كائنات) محددة ضمن مواصفة JSON ككائنات مخطط.

هيكل OpenAPI

مواصفة OpenAPI هي وثيقة تصف الهيكل والسلوك لـ REST APIs. دعنا نتعمق أكثر في وثيقة OpenAPI.

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

يمكن أن تتضمن وثيقة OpenAPI الأقسام التالية:

OpenAPI: تتطلب الـ API تحديد إصدار OpenAPI لتمكين الأدوات من تحليل مواصفة OpenAPI وتوليد الوثائق.
Info: يحتوي هذا الحقل على بيانات وصفية حول الـ API، مثل عنوانه، وصفه، وإصداره. يمكن أن تستفيد الأدوات المختلفة من هذه المعلومات.
Servers: يتكون هذا الحقل في مواصفة OpenAPI من مصفوفة من كائنات الخادم، كل منها يحتوي على عنوان URL لعنوان الخادم ووصف موجز للخادم. توفر هذه المعلومات تفاصيل الاتصال التي يمكنك استخدامها للتفاعل مع الخادم.
Paths: يحتوي هذا الكائن على المسارات النسبية لنقاط نهاية الـ API المنفصلة. يتضمن كل مسار العمليات المتاحة للتفاعل مع الـ API، مثل POST، GET، PUT، أو DELETE.
Components: هذا الحقل في مواصفة OpenAPI هو كائن يحتوي على مخططات قابلة لإعادة الاستخدام لهيئات الطلب، ومخططات الاستجابة، ومخططات الأمان. يمكن الإشارة إلى هذه المخططات في جميع أنحاء المواصفة باستخدام علامة $ref، خصوصًا في كائن المسار.
Security: كائن يعلن عن نوع مخطط الأمان الذي يخول الطلبات. يتم تعريف كائن الأمان بشكل عالمي أو يتم تجاوزها بواسطة عمليات فردية.
Tags: كائن يحتوي على بيانات وصفية تحدد ترتيب عرض موارد الـ API في الوثائق.
ExternalDocs: كائن يربط بمزيد من الوثائق، مثل أدلة المستخدم.

إليك القالب الأساسي لوثيقة OpenAPI مع الحقول المطلوبة بتنسيق YAMLJSON.

طلب POST

تم تعريف نقطة النهاية التالية لطلب POST لتحميل صورة لحيوان أليف.

openapi: 3.0.3
info:
  title: متجر حيوانات أليفة Swagger - OpenAPI 3.0
  version: 1.0.11
servers:
  - url: https://petstore3.swagger.io/api/v3
tags:
  - name: حيوان أليف
    description: كل شيء عن حيواناتك الأليفة

paths:
  /pet/{petId}/uploadImage:
    post:
      tags:
        - حيوان أليف
      summary: تحميل صورة
      description: ''
      operationId: uploadFile
      parameters:
        - name: petId
          in: path
          description: ID للحيوان الأليف لتحديثه
          required: true
          schema:
            type: integer
            format: int64
        - name: additionalMetadata
          in: query
          description: بيانات إضافية
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: عملية ناجحة

يمكنك تنفيذ مقتطف الشيفرة أعلاه في https://editor.swagger.io/. ستكون النتيجة كما يلي.

يبدأ مقتطف الشيفرة بتوفير معلومات أساسية حول الـ API، مثل عنوانه وإصداره. كما يحدد عنوان URL الأساسي لخادم الـ API.

يحدد قسم tags علامة تسمى "حيوان أليف" تجمع جميع نقاط النهاية المتعلقة بالحيوانات الأليفة. يحتوي قسم paths على تعريف لنقطة النهاية /pet/{petId}/uploadImage.

تدعم نقطة النهاية /pet/{petId}/uploadImage طريقة POST لتحميل صورة لحيوان أليف. يحدد قسم المعلمات معلمتين، "petId" و"additionalMetadata"، اللتين تحددان ID الحيوان الأليف الذي سيتم تحديثه وأي بيانات إضافية لصورة التحميل، على التوالي.

تحدد قسم request body هيكل جسم الطلب، الذي من المتوقع أن يكون بتنسيق ثنائي. يحدد قسم الاستجابات رمز استجابة واحد، 200، مما يدل على نجاح العملية.

ما هي فوائد OpenAPI؟

تقدم مواصفة OpenAPI العديد من الفوائد للمطورين الذين يقومون ببناء وتوثيق الـ APIs.

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

يمكن للمطورين توليد كود للـ APIs بعدة لغات برمجة، مع الحفاظ على الاتساق عبر اللغات. تكون ملفات الوثائق التي تم توليدها موثوقة ومتسقة، بينما توفر أيضًا الوقت للمطورين.

تساعد أدوات التحقق في ضمان التوافق ومنع الأخطاء، بينما يبسط نظام غني من الأدوات عملية تطوير الـ API بالكامل. تقلل مواصفة OpenAPI من الأخطاء وتحسن جودة مشاريع البرمجيات الناتجة.

كيفية إنشاء مواصفة OpenAPI

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

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

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

دعنا نلقي نظرة على دليل خطوة بخطوة حول كيفية القيام بذلك. إليك عملية خطوة بخطوة لاستيراد ملف مواصفة OpenAPI إلى Apidog:

الخطوة 1. فتح موقع Apidog

أولاً، افتح موقع Apidog في متصفح الويب الخاص بك. يمكنك الوصول إليه بزيارة موقعهم.

الخطوة 2. تسجيل الدخول إلى حسابك

إذا كان لديك حساب API Dog موجود، قم بتسجيل الدخول من خلال النقر على زر "تسجيل الدخول" في الزاوية العليا اليمنى من الصفحة. إذا لم يكن لديك حساب، يمكنك إنشاء واحد من خلال النقر على زر "تسجيل" واتباع التعليمات.

الخطوة 3. إنشاء مشروع جديد

بمجرد تسجيل الدخول، انقر على زر "إنشاء مشروع" لإنشاء مشروع جديد.

الخطوة 4. استيراد ملف OpenAPI

استورد ملف مواصفة OpenAPI في صفحة إنشاء المشروع. انقر على زر "استيراد" للمتابعة.

الخطوة 5. رفع ملف OpenAPI الخاص بك:

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

إدخال عنوان URL الخاص بملف JSON الخاص بي.

الخطوة 6. انتظار اكتمال الاستيراد

اعتمادًا على حجم وتعقيد ملف OpenAPI الخاص بك، قد تستغرق عملية الاستيراد بضع دقائق.

سيقوم Apidog بتحليل الملف تلقائيًا وتوليد API جديدة في حسابك.

الخطوة 7. تكوين إعدادات الـ API الخاصة بك

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

الخطوة 8. ابدأ في بناء الـ API الخاص بك

بمجرد تكوين إعدادات الـ API الخاصة بك، يمكنك إضافة نقاط النهاية والوثائق إلى الـ API الخاص بك باستخدام واجهة Apidog السهلة الاستخدام.

من خلال اتباع الخطوات البسيطة لاستيراد ملف مواصفة OpenAPI إلى Apidog، يمكنك إدارة وتوثيق مشاريع الـ API الخاصة بك بشكل أكثر كفاءة. عادةً ما يتضمن ملف المواصفة التفاصيل الأساسية مثل نقطة النهاية POST، والمسار، والمعلمات، وأكواد الاستجابة.

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