ما التغييرات في OpenAPI 3.2 مقارنة بـ 3.1 و 3.0؟

باختصار

أضافت OpenAPI 3.1 التوافق الكامل مع JSON Schema، وwebhooks، وتحسينات على الـ discriminator. أضافت OpenAPI 3.2 دعم طريقة QUERY، وأمثلة محسنة، وتعاريف أمان أفضل. يستخدم Modern PetstoreAPI الإصدار 3.2 من OpenAPI لعرض أحدث الميزات مع أمثلة جاهزة للإنتاج.

مقدمة

أنت تكتب مواصفات OpenAPI. ترى إشارات إلى OpenAPI 3.0 و 3.1 و 3.2. ما الفرق؟ هل يجب عليك الترقية؟ هل ستدعم أدواتك الإصدار الجديد؟

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

يستخدم Swagger Petstore القديم OpenAPI 2.0 (مواصفات Swagger). يستخدم Modern PetstoreAPI OpenAPI 3.2، ويعرض كل ميزة جديدة بأمثلة جاهزة للإنتاج.

في هذا الدليل، ستتعرف على ما تغير في كل إصدار من OpenAPI، وكيفية اختيار الإصدار الصحيح، وكيف يعرض Modern PetstoreAPI ميزات OpenAPI 3.2.

OpenAPI 3.0 الأساسي

كان OpenAPI 3.0 (صدر في يوليو 2017) ترقية رئيسية من Swagger 2.0.

الميزات الرئيسية

1. خوادم متعددة

servers:
  - url: https://api.petstoreapi.com/v1
    description: Production
  - url: https://staging.petstoreapi.com/v1
    description: Staging

كان Swagger 2.0 يدعم مضيفًا واحدًا فقط.

2. كائن نص الطلب (Request body object)

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'

أكثر وضوحًا من معلمة body في Swagger 2.0.

3. المكونات لإعادة الاستخدام

components:
  schemas:
    Pet:
      type: object
  responses:
    NotFound:
      description: Resource not found
  parameters:
    PetId:
      name: petId
      in: path

تنظيم أفضل من definitions في Swagger 2.0.

4. الـ Callbacks

تعريف الـ callbacks غير المتزامنة (webhooks):

callbacks:
  orderUpdate:
    '{$request.body#/callbackUrl}':
      post:
        requestBody:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderUpdate'

5. الروابط

تعريف العلاقات بين العمليات:

links:
  GetPetByPetId:
    operationId: getPetById
    parameters:
      petId: '$response.body#/id'

القيود

1. عدم توافق JSON Schema

استخدمت OpenAPI 3.0 مجموعة فرعية من JSON Schema Draft 5، وليس JSON Schema الكامل. تسبب هذا في مشاكل في التحقق من الصحة.

2. عدم وجود كائن webhooks

تم تعريف الـ webhooks كـ callbacks، مما كان مربكًا.

3. محدودية الـ discriminator

كان دعم التعددية (Polymorphism) أساسيًا.

4. عدم وجود نوع null

لم يكن بإمكانك تحديد type: null مباشرة.

التغييرات الرئيسية في OpenAPI 3.1

ركز OpenAPI 3.1 (صدر في فبراير 2021) على محاذاة JSON Schema.

1. التوافق الكامل مع JSON Schema 2020-12

أكبر تغيير: مخططات OpenAPI 3.1 هي JSON Schema 2020-12 صالحة.

قبل (OpenAPI 3.0):

type: string
nullable: true  # OpenAPI-specific

بعد (OpenAPI 3.1):

type: [string, "null"]  # Standard JSON Schema

الفوائد:

• استخدام أي مدقق JSON Schema
• مشاركة المخططات بين OpenAPI والأدوات الأخرى
• الوصول إلى ميزات JSON Schema الكاملة

2. كائن Webhooks

قبل (OpenAPI 3.0):

# Webhooks defined as callbacks (confusing)
paths:
  /subscribe:
    post:
      callbacks:
        orderUpdate:
          # webhook definition

بعد (OpenAPI 3.1):

webhooks:
  orderUpdate:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdate'

فصل أوضح بين نقاط نهاية API والـ webhooks.

3. تحسين الـ Discriminator

دعم أفضل للتعددية:

oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
discriminator:
  propertyName: petType
  mapping:
    cat: '#/components/schemas/Cat'
    dog: '#/components/schemas/Dog'

4. مُعرّف ترخيص كائن المعلومات (Info Object License Identifier)

info:
  license:
    name: MIT
    identifier: MIT  # SPDX identifier

5. مرجع عنصر المسار ($ref PathItem)

الإشارة إلى عناصر المسار بأكملها:

paths:
  /pets:
    $ref: '#/components/pathItems/PetsCollection'

التغييرات الجوهرية

1. إزالة nullable

استخدم type: [string, "null"] بدلاً من ذلك.

2. تغيير exclusiveMinimum/exclusiveMaximum

أصبح الآن منطقيًا (boolean)، وليس رقميًا.

3. example مقابل examples

تحقق من صحة أكثر صرامة.

أحدث ميزات OpenAPI 3.2

يضيف OpenAPI 3.2 (تاريخ الإصدار سيحدد لاحقًا، المسودة متاحة) أنماط API حديثة.

1. دعم طريقة QUERY

طريقة HTTP QUERY لعمليات البحث المعقدة:

paths:
  /pets/search:
    query:  # New method
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                sort:
                  type: array
      responses:
        '200':
          description: Search results

يستخدم Modern PetstoreAPI طريقة QUERY لعمليات البحث المعقدة عن الحيوانات الأليفة.

2. أمثلة محسنة

أمثلة متعددة مع بيانات تعريف:

examples:
  availableCat:
    summary: Available cat
    description: A cat available for adoption
    value:
      id: "019b4132-70aa-764f-b315-e2803d882a24"
      name: "Fluffy"
      species: "CAT"
      status: "AVAILABLE"
  adoptedDog:
    summary: Adopted dog
    value:
      id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
      name: "Buddy"
      species: "DOG"
      status: "ADOPTED"

3. تعاريف أمان محسّنة

دعم أفضل لـ OAuth 2.0:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://petstoreapi.com/oauth/authorize
          tokenUrl: https://petstoreapi.com/oauth/token
          refreshUrl: https://petstoreapi.com/oauth/refresh
          scopes:
            pets:read: Read pets
            pets:write: Create and update pets
            orders:read: Read orders

4. تحسين تعيين الـ Discriminator

تعددية أكثر مرونة:

discriminator:
  propertyName: type
  mapping:
    cat: Cat
    dog: Dog
    bird: '#/components/schemas/Bird'  # Can mix local and $ref

5. دعم أفضل لإهمال الميزات

إهمال حقول محددة:

properties:
  oldField:
    type: string
    deprecated: true
    description: Use newField instead
  newField:
    type: string

كيف يستخدم Modern PetstoreAPI الإصدار OpenAPI 3.2

يعرض Modern PetstoreAPI كل ميزة من ميزات OpenAPI 3.2.

1. مواصفات كاملة

المواصفات الكاملة لـ OpenAPI 3.2 متاحة على:

https://petstoreapi.com/openapi.json

2. طريقة QUERY لعمليات البحث المعقدة

/pets/search:
  query:
    summary: Search pets with complex criteria
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PetSearchQuery'

3. الـ Webhooks

webhooks:
  petStatusChanged:
    post:
      summary: Pet status changed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetStatusWebhook'

4. المخططات متعددة الأشكال (Polymorphic Schemas)

Pet:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Bird'
  discriminator:
    propertyName: species

5. أمثلة شاملة

تتضمن كل نقطة نهاية أمثلة متعددة توضح سيناريوهات مختلفة.

6. استجابات الخطأ RFC 9457

responses:
  '400':
    description: Bad Request
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'

راجع مواصفات OpenAPI الكاملة لجميع الميزات.

دليل الترحيل

من 3.0 إلى 3.1

1. استبدال nullable:

# Before
type: string
nullable: true

# After
type: [string, "null"]

2. تحديث exclusiveMinimum/exclusiveMaximum:

# Before
minimum: 0
exclusiveMinimum: true

# After
minimum: 0
exclusiveMinimum: 0

3. نقل الـ webhooks:

# Before
paths:
  /subscribe:
    callbacks:
      # webhook

# After
webhooks:
  # webhook

من 3.1 إلى 3.2

1. إضافة طرق QUERY حيثما كان ذلك مناسبًا:

/pets/search:
  query:  # New in 3.2
    # complex search

2. تحسين الأمثلة:

examples:
  example1:
    summary: Description
    value: {...}

3. تحديث تعاريف الأمان:

أضف refreshUrl إلى تدفقات OAuth.

اختبار مواصفات OpenAPI باستخدام Apidog

يدعم Apidog جميع إصدارات OpenAPI.

استيراد مواصفات OpenAPI

1. افتح Apidog
2. انقر على "استيراد"
3. اختر "OpenAPI 3.x"
4. الصق الرابط أو حمّل الملف
5. يقوم Apidog بالتحقق من الصحة والاستيراد

التحقق من صحة المواصفات

يتحقق Apidog من:

• صحة المخطط (Schema validity)
• سلامة المراجع (Reference integrity)
• صحة الأمثلة (Example correctness)
• اكتمال تعريف الأمان (Security definition completeness)

اختبار تطبيق API

إنشاء حالات اختبار من المواصفات:

• التحقق من صحة الطلب
• التحقق من صحة الاستجابة
• فحوصات رمز الحالة
• التوافق مع المخطط

مقارنة الإصدارات

استيراد إصدارات متعددة ومقارنتها:

• التغييرات الجوهرية (Breaking changes)
• نقاط نهاية جديدة
• تغييرات المخطط
• الحقول المهملة

الخلاصة

تطورت OpenAPI بشكل كبير:

OpenAPI 3.0: الأساس مع الخوادم، نصوص الطلبات، Callbacks

OpenAPI 3.1: توافق JSON Schema، كائن webhooks، تعددية أفضل

OpenAPI 3.2: طريقة QUERY، أمثلة محسنة، أمان محسّن

يستخدم Modern PetstoreAPI الإصدار OpenAPI 3.2 لعرض جميع الميزات مع أمثلة جاهزة للإنتاج. إنه التطبيق المرجعي لتصميم API الحديث.

استخدم Apidog للعمل مع أي إصدار من OpenAPI، والتحقق من صحة المواصفات، واختبار التطبيقات.

الأسئلة الشائعة

هل يجب علي الترقية إلى OpenAPI 3.1 أو 3.2؟

إذا كانت أدواتك تدعم ذلك، فنعم. توافق OpenAPI 3.1 مع JSON Schema ذو قيمة. يضيف OpenAPI 3.2 أنماطًا حديثة مثل طريقة QUERY.

هل ستعمل مواصفات OpenAPI 3.0 الخاصة بي مع أدوات 3.1؟

في الغالب، ولكن nullable و exclusiveMinimum/exclusiveMaximum تحتاج إلى تحديثات.

هل تدعم مولدات الكود OpenAPI 3.2؟

الدعم يتزايد. تحقق من وثائق المولد الخاص بك. يدعم العديد الإصدار 3.1، وعدد أقل يدعم 3.2.

هل يمكنني استخدام ميزات OpenAPI 3.2 في 3.1؟

لا. استخدم الإصدار الذي يتوافق مع ميزاتك. إذا كنت تحتاج إلى طريقة QUERY، استخدم 3.2.

كيف أقوم بالتحقق من صحة مواصفات OpenAPI الخاصة بي؟

استخدم Apidog لاستيراد مواصفاتك والتحقق من صحتها. يقوم بفحص صحة المخطط وسلامة المراجع.

أين يمكنني رؤية مثال كامل لـ OpenAPI 3.2؟

يوفر Modern PetstoreAPI مواصفات OpenAPI 3.2 كاملة وجاهزة للإنتاج.

ما الفرق بين الـ webhooks والـ callbacks؟

الـ webhooks هي طلبات HTTP من الخادم إلى العميل. الـ callbacks تُعرّف في OpenAPI 3.0 كجزء من العمليات. يحتوي OpenAPI 3.1+ على كائن webhooks مخصص.

هل يجب علي استخدام JSON أو YAML لمواصفات OpenAPI؟

كلاهما يعمل. YAML أكثر قابلية للقراءة للبشر. JSON أسهل للأدوات. يوفر Modern PetstoreAPI كلا التنسيقين.