كيفية التحكم في إصدار مواصفات OpenAPI باستخدام Git

مواصفات OpenAPI الخاصة بك هي عقد بين الخادم والعملاء. إذا تغيّر العقد بدون مراجعة، قد تتعطل تطبيقات العملاء، تصبح الـ mocks قديمة، وتعمل الاختبارات ضد API لم يعد موجودًا. لذلك تعامل مع openapi.yaml مثل الكود: ضعه في Git، اعمل عليه عبر فروع، راجعه في Pull Requests، وشغّل التحقق الآلي عند كل تغيير.

جرّب Apidog اليوم

في هذا الدليل سنبني سير عمل عملي للتحكم في إصدار OpenAPI باستخدام Git: أين تضع ملف المواصفات، كيف تنشئ فروعًا لتغييرات العقد، ماذا يراجع الفريق في Pull Request، كيف تضيف فحوصات CI، وكيف تدفع التغييرات مباشرة من Apidog.

لماذا تتحكم في إصدار مواصفات OpenAPI؟

المواصفات الموجودة في Wiki أو Drive مشترك لا تملك سجلًا موثوقًا. لا يمكنك معرفة من غيّر حمولة POST /orders أو لماذا. Git يحل هذه المشكلة.

عند وضع openapi.yaml تحت التحكم في الإصدار تحصل على:

• سجل تغييرات واضح: كل تعديل هو commit بمؤلف وتاريخ ورسالة.
• تتبّع المسؤولية: استخدم git blame openapi.yaml لمعرفة من أضاف حقلًا أو غيّر نوعًا.
• استرجاع سريع: إذا كسر merge العقد، يمكنك الرجوع إلى commit سابق.
• مراجعة قبل الدمج: تمر تغييرات API عبر Pull Requests بدل التعديل المباشر.

هذا هو أساس سير عمل واجهة برمجة التطبيقات الأصلي لـ Git: المواصفات هي كود مصدر، والكود المصدر يعيش في Git.

أين تضع ملف OpenAPI داخل المستودع؟

ابدأ ببنية بسيطة ومتوقعة. الخيار العملي لمعظم الفرق هو وضع ملف واحد داخل مجلد api/:

my-service/
├── api/
│   └── openapi.yaml
├── src/
└── README.md

إذا كنت تحتفظ بعدة إصدارات رئيسية في الوقت نفسه، افصل كل إصدار في ملف مستقل:

api/
├── api-v1.yaml
└── api-v2.yaml

هذا يساعدك على:

• إبقاء api-v1.yaml مستقرًا للعملاء الحاليين.
• تطوير api-v2.yaml بدون خلط تغييرات غير متوافقة.
• تقليل حجم الـ diff في Pull Requests.
• تسهيل مراجعة كل تغيير حسب الإصدار.

هذه هي الفكرة العملية وراء مواصفات API كرمز.

اختر قاعدة واحدة ووثّقها في README.md. لا تترك أكثر من ملف يدّعي أنه “المواصفات الرسمية”.

استراتيجية التفريع لتغييرات OpenAPI

لا تحتاج إلى نموذج تفريع خاص بالمواصفات. استخدم نفس تدفق الكود:

git checkout main
git pull
git checkout -b api/add-refunds

ثم عدّل api/openapi.yaml، شغّل التحقق، وافتح Pull Request.

استخدم أسماء فروع واضحة:

نوع التغيير	النمط	مثال
نقطة نهاية جديدة	api/add-<resource>	api/add-refunds
تغيير حقل	api/change-<resource>-<field>	api/change-order-status
تغيير جوهري	api/breaking-<description>	api/breaking-v2-auth
إصلاح أو تنظيف	api/fix-<description>	api/fix-pagination-schema

البادئة api/ تجعل Pull Request واضحًا للمراجعين وCI: هذا التغيير يمس عقد API.

للتغييرات الجوهرية، استخدم breaking- صراحةً حتى يعرف الفريق أن التغيير قد يحتاج إلى إصدار رئيسي جديد أو خطة ترحيل.

حافظ على الفروع قصيرة العمر. فرع مواصفات يعيش أسبوعين غالبًا سيتعارض مع تغييرات الفريق. الأفضل: تغيير منطقي واحد، Pull Request صغير، ثم merge.

كيف تراجع تغييرات المواصفات في Pull Request؟

Pull Request لمواصفات OpenAPI ليس تعديلًا شكليًا؛ إنه تغيير في العقد. راجعه مثل مراجعة كود يؤثر على المستخدمين.

اكتب YAML بطريقة سهلة للمراجعة. مثال:

paths:
  /orders/{orderId}:
    get:
      summary: Get an order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"

قواعد عملية لتقليل الضوضاء في diff:

• استخدم ترتيبًا ثابتًا للحقول.
• اجعل كل حقل في سطر مستقل.
• تجنّب إعادة تنسيق الملف بالكامل في نفس PR.
• لا تخلط تغييرات schema مع تغييرات وصفية غير ضرورية.

قائمة مراجعة للمراجعين

افحص هذه النقاط في كل Pull Request:

• التغييرات الجوهرية
  
  هل تمت إضافة حقل مطلوب؟ هل حُذف حقل من response؟ هل تغيّر نوع حقل؟ هل تمت إزالة قيمة من enum؟

• التوافق مع الإصدارات السابقة
  
  إضافة endpoint جديد أو حقل اختياري غالبًا آمنة. تغيير شكل response موجود قد يكسر العملاء.

• الاتساق في التسمية
  
  هل تستخدم نفس نمط الجمع، casing، وأسماء الموارد الموجودة؟

• اكتمال العملية
  
  كل operation جديدة تحتاج إلى summary، responses، schemas، وأخطاء متوقعة.

• الأمثلة
  
  الأمثلة الواقعية تجعل الوثائق والـ mocks والاختبارات أكثر فائدة.

لا تعتمد فقط على العين البشرية لاكتشاف breaking changes. أضف فحص CI يقارن مواصفات PR مع main.

الالتزام والدفع من Apidog

تحرير YAML يدويًا يعمل، لكنه يصبح مزعجًا عندما تكبر المواصفات. محرر مرئي مع تحقق مباشر يقلل الأخطاء ويجعل التعديل أسرع.

يوفر وضع Apidog Spec-First مزامنة Git ثنائية الاتجاه:

1. اربط مستودع Git.
2. حدّد ملف المواصفات مثل api/openapi.yaml.
3. عدّل endpoints وschemas وexamples من الواجهة.
4. اترك Apidog يكتب YAML متناسقًا.
5. أنشئ commit على فرعك وادفعه إلى المستودع.
6. افتح Pull Request كالمعتاد.

الفائدة العملية هنا أن diff يبقى قابلًا للمراجعة: لا إعادة ترتيب عشوائية ولا إعادة تنسيق مزعجة. يمكنك قراءة الإعداد الكامل في وثائق وضع Apidog Spec-First. وإذا كنت تريد مزامنة الملف مع GitHub تحديدًا، راجع مزامنة مواصفات OpenAPI الخاصة بك مع GitHub.

أضف فحوصات CI لمواصفات OpenAPI

لا تسمح بوصول مواصفات غير صالحة إلى main. اجعل Pull Request يفشل تلقائيًا إذا كان openapi.yaml غير صالح.

مثال GitHub Actions بسيط باستخدام Redocly:

name: Validate OpenAPI

on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Lint spec
        run: npx @redocly/cli lint api/openapi.yaml

ابدأ بهذا الفحص، ثم أضف فحوصات أخرى تدريجيًا:

• linting للأسلوب والبنية.
• التحقق من أن الملف صالح كـ OpenAPI 3.x.
• مقارنة PR مع main لاكتشاف breaking changes.
• منع الدمج إذا وُجد تغيير جوهري غير مقصود.

مثال عملي لاستخدام oasdiff لاكتشاف التغييرات الجوهرية:

name: OpenAPI Breaking Changes

on: [pull_request]

jobs:
  breaking-check:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install oasdiff
        run: |
          curl -L https://github.com/Tufin/oasdiff/releases/latest/download/oasdiff_linux_amd64.tar.gz \
            | tar xz
          sudo mv oasdiff /usr/local/bin/oasdiff

      - name: Compare with main
        run: |
          git fetch origin main
          git show origin/main:api/openapi.yaml > /tmp/openapi-main.yaml
          oasdiff breaking /tmp/openapi-main.yaml api/openapi.yaml

بهذا يصبح اكتشاف التغييرات الخطرة جزءًا من سير العمل بدل الاعتماد على المراجعة اليدوية فقط.

أفضل الممارسات للتحكم في إصدار OpenAPI

استخدم هذه القواعد للحفاظ على مواصفات مستقرة وقابلة للمراجعة:

• استخدم الترقيم الدلالي للإصدارات
  
  حدّث info.version. التغيير الجوهري يعني إصدارًا رئيسيًا جديدًا، والإضافات المتوافقة تزيد الإصدار الثانوي.

• احتفظ بسجل تغييرات
  
  ضع CHANGELOG.md بجانب المواصفات لتوضيح ما تغيّر بين الإصدارات.

• اجعل Pull Requests صغيرة
  
  تغيير منطقي واحد لكل PR. الطلبات الكبيرة تخفي breaking changes وسط الضوضاء.

• اكتب رسائل commit واضحة
  
  مثال جيد:
  

  git commit -m "Add refundReason to refund request schema"

أفضل من:

  git commit -m "Update spec"

• لا تعدّل main مباشرة
  
  حتى إصلاح خطأ مطبعي يجب أن يمر عبر فرع وPull Request.

• ثبّت تنسيق YAML
  
  استخدم أداة واحدة أو محررًا واحدًا لتجنب اختلافات formatting غير مفيدة.

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

كيف أكتشف التغييرات الجوهرية في مواصفات OpenAPI؟

شغّل أداة مقارنة في CI تقارن ملف PR بالنسخة الموجودة على main. أدوات مثل oasdiff يمكنها تصنيف التغييرات كجوهري أو غير جوهري، وتفشل البناء عند وجود تغيير غير متوافق.

هذا يساعد على اكتشاف حالات مثل:

• حذف حقل من response.
• إضافة parameter مطلوب.
• تغيير نوع حقل من string إلى integer.
• إزالة قيمة من enum.

هل أستخدم ملف OpenAPI واحدًا أم أقسمه إلى عدة ملفات؟

ابدأ بملف واحد: api/openapi.yaml. هذا أسهل للمراجعة والـ versioning.

قسّم فقط عندما تظهر حاجة فعلية، مثل:

• وجود إصدارات رئيسية متعددة: api-v1.yaml وapi-v2.yaml.
• تضخم الملف بشكل يصعّب القراءة.
• الحاجة إلى فصل schemas باستخدام $ref.

لا تقسّم مبكرًا. ملف واحد واضح أفضل من عدة ملفات مشتتة.

هل يمكنني التحكم في إصدار المواصفات دون كتابة YAML يدويًا؟

نعم. يتيح وضع Apidog Spec-First تحرير المواصفات من محرر مرئي ومزامنتها مع Git في الاتجاهين. النتيجة: YAML متناسق، diffs نظيفة، Pull Requests قابلة للقراءة، مع الاحتفاظ بسجل Git الكامل والمراجعة المعتادة.