DEV Community

Cover image for ما هو سير عمل API الأصلي لـ Git؟ وكيف تبني واحداً؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

ما هو سير عمل API الأصلي لـ Git؟ وكيف تبني واحداً؟

يعيش الكود الخاص بك في Git. تعيش خطوط أنابيب CI والمراجعات وسجل الإصدارات في Git. لذلك يجب أن تعيش مواصفات API الخاصة بك هناك أيضًا، كملف OpenAPI عادي داخل المستودع.

جرّب Apidog اليوم

في سير عمل API الأصلي لـ Git، تتعامل مع ملف openapi.yaml أو openapi.json مثل أي ملف كود آخر: تعدّله، تراجعه عبر Pull Request، تشغّل عليه CI، ثم تدمجه. لا تحتاج إلى قاعدة بيانات سحابية منفصلة أو خطوات تصدير/استيراد متكررة.

💡 يدعم Apidog هذا من خلال وضع Spec-First Mode. يمكنك تصميم API في محرر بأسلوب IDE، ثم مزامنة ملفات OpenAPI الخام ثنائيًا مع GitHub أو GitLab.

ماذا يعني سير عمل API الأصلي لـ Git

سير عمل API الأصلي لـ Git يعني أن مواصفات API تعيش داخل المستودع بجانب الكود:

repo/
├── src/
├── tests/
├── openapi.yaml
└── .github/workflows/
Enter fullscreen mode Exit fullscreen mode

كل تغيير في العقد يصبح commit يمكن تتبعه ومراجعته.

هذا يمنحك عمليًا:

  • سجل إصدارات واضح: يمكنك معرفة من غيّر نقطة نهاية ومتى باستخدام git log أو git blame.
  • مراجعة عبر Pull Requests: تظهر تغييرات المسارات، الاستجابات، والـ schemas كـ diff قبل الدمج.
  • مصدر واحد للحقيقة: الملف الموجود في main هو العقد الذي تقرأ منه الوثائق، الاختبارات، والمحاكاة.

مثال عملي:

git checkout -b api/add-order-status
# عدّل openapi.yaml
git diff openapi.yaml
git add openapi.yaml
git commit -m "Add order status enum values"
git push origin api/add-order-status
Enter fullscreen mode Exit fullscreen mode

هذه هي الفكرة الأساسية وراء تطوير API الذي يركز على المواصفات: المواصفات تقود، والتطبيق يتبع. لمزيد من التفاصيل، راجع دليل تطوير API الذي يركز على المواصفات.

مشكلة مواصفات API المقيدة بالسحابة

عندما تحتفظ أداة تصميم API بالمواصفات داخل قاعدة بياناتها الخاصة، يصبح “الملف” الذي تعمل عليه غير موجود فعليًا في مستودعك. هذا يسبب احتكاكًا واضحًا في فرق التطوير.

أبرز المشاكل:

  • المراجعة تحدث في مكانين: الكود في GitHub أو GitLab، والمواصفات في أداة منفصلة.
  • الفرق غير مرئي بوضوح: لا تحصل على diff سطر بسطر داخل Pull Request.
  • التصدير يصبح خطوة إلزامية: تحتاج إلى تصدير المواصفات ثم الالتزام بها يدويًا.
  • CI يحتاج ملفًا على القرص: أدوات linting، اختبارات العقود، وتوليد الكود تعمل بشكل أفضل عندما يكون ملف OpenAPI داخل المستودع.

بدلًا من ذلك، اجعل المواصفات ملفًا حقيقيًا:

openapi.yaml
Enter fullscreen mode Exit fullscreen mode

ثم شغّل عليه أدواتك مباشرة:

npx @redocly/cli lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

أو:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o generated/client
Enter fullscreen mode Exit fullscreen mode

هذا هو جوهر مفهوم مواصفات API ككود: الملف هو المواصفات، وGit هو التاريخ، وCI هو التنفيذ.

كيف يعمل وضع Apidog Spec-First Mode

وضع Spec-First Mode مصمم للفرق التي تدير العمل عبر الفروع والالتزامات. بدلًا من تحرير API فقط عبر نماذج مرئية، يمكنك العمل على ملفات YAML أو JSON خام، مع مزامنة ثنائية الاتجاه مع Git.

1. تحرير OpenAPI في محرر بأسلوب IDE

تكتب المواصفات داخل محرر أكواد، مع ميزات تساعدك أثناء التنفيذ:

  • تمييز بناء الجملة لـ YAML وJSON.
  • التحقق من صحة OpenAPI وSwagger أثناء الكتابة.
  • الإكمال التلقائي للكلمات المفتاحية والأنواع والمراجع.
  • عرض الأخطاء مبكرًا قبل وصولها إلى CI.

2. العمل على ملفات YAML/JSON خام

مثال على ملف OpenAPI قابل للإدارة داخل Git:

openapi: 3.1.0
info:
  title: Orders API
  version: 1.2.0

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

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]
Enter fullscreen mode Exit fullscreen mode

هذا الملف هو ما يتم الالتزام به ودفعه إلى Git. لا توجد حقول مخفية أو بيانات وصفية منفصلة لا تراها في المستودع.

3. التنقل داخل المواصفات الطويلة

أثناء التحرير، يحلل Apidog ملف OpenAPI ويبني مخططًا تفصيليًا في الشريط الجانبي. يمكنك الانتقال مباشرة إلى:

  • paths
  • العمليات مثل getOrder
  • المخططات داخل components.schemas
  • الاستجابات والمعاملات

هذا مفيد عندما يصبح ملف OpenAPI كبيرًا ويحتوي على عشرات أو مئات نقاط النهاية.

4. مزامنة Git ثنائية الاتجاه

يدعم وضع Spec-First Mode مزامنة الملفات مع:

  • GitHub
  • GitLab
  • Azure DevOps عبر اتصال Git

سير العمل العملي:

Pull latest changes
→ Edit OpenAPI file
→ Commit
→ Push
→ Review through PR
Enter fullscreen mode Exit fullscreen mode

إذا عدّل زميلك نفس ملف المواصفات، يمكنك سحب التغييرات ومراجعة الفروقات كما تفعل مع الكود.

5. الالتزام والدفع من داخل Apidog

يمكنك إدارة التغييرات من داخل Apidog:

  1. راجع الملفات المعدلة أو المضافة أو المحذوفة.
  2. اكتب رسالة commit واضحة.
  3. ادفع التغيير إلى الفرع المتتبع.
  4. تحقق من حالة المزامنة.

مثال على رسائل commit جيدة:

Add 404 response for getOrder
Enter fullscreen mode Exit fullscreen mode 
Update Order schema with deliveryStatus field
Enter fullscreen mode Exit fullscreen mode

تجنب الرسائل العامة مثل:

Update spec
Enter fullscreen mode Exit fullscreen mode

لشرح مركز حول GitHub، راجع مزامنة مواصفات OpenAPI مع GitHub.

شرح الإعداد

فيما يلي سير إعداد عملي من مستودع إلى مواصفات متزامنة. المرجع الكامل متاح في وثائق وضع Spec-First Mode.

الخطوة 1: أنشئ مشروعًا من مستودع Git

ابدأ مشروع Spec-First جديدًا في Apidog، ثم اربط مزود Git الخاص بك. اختر:

  • المستودع الذي يحتوي على ملف OpenAPI.
  • الفرع الذي تريد تتبعه، غالبًا main.
  • ملف المواصفات مثل openapi.yaml.

الخطوة 2: حرّر المواصفات

افتح ملف OpenAPI وعدّل ما تحتاجه. على سبيل المثال، إضافة استجابة 404:

responses:
  "404":
    description: Order not found
Enter fullscreen mode Exit fullscreen mode

أثناء الكتابة، يساعدك المحرر عبر:

  • التحقق من البنية.
  • الإكمال التلقائي.
  • تحديث مخطط التنقل الجانبي.

الخطوة 3: راجع الملفات المتغيرة

يعرض Apidog الملفات التي تغيرت منذ آخر مزامنة، مثل:

modified: openapi.yaml
added: schemas/payment.yaml
deleted: old-spec.json
Enter fullscreen mode Exit fullscreen mode

راجع هذه القائمة قبل الالتزام حتى تعرف بالضبط ما سيدخل إلى Git.

الخطوة 4: اكتب رسالة commit واضحة

اكتب رسالة تصف التغيير الفني بدقة:

Add payment schema to OpenAPI spec
Enter fullscreen mode Exit fullscreen mode

أو:

Rename orderStatus enum values
Enter fullscreen mode Exit fullscreen mode

الخطوة 5: ادفع التغيير

ادفع الالتزام إلى الفرع المتتبع. بعد ذلك يمكن لفريقك فتح Pull Request أو تشغيل CI حسب سير العمل المعتاد.

الخطوة 6: تحقق من حالة المزامنة

راقب مؤشر حالة المزامنة. عندما يظهر أن الحالة متزامنة، فهذا يعني أن تعديلاتك المحلية والفرع البعيد متطابقان.

الحلقة الكاملة تصبح:

Pull → Edit → Commit → Push → Verify
Enter fullscreen mode Exit fullscreen mode

بدون تصدير، وبدون مصدر ثانٍ للحقيقة.

وضع Spec-First مقابل وضع Design-First

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

وضع Spec-First، تجريبي وضع Design-First
تخزين المواصفات ملفات YAML/JSON خام في Git مشروع Apidog السحابي
المحرر الأساسي محرر أكواد بأسلوب IDE واجهة مستخدم بصرية تعتمد على النماذج
التحكم في الإصدارات Git أصلي: commits، branches، diffs سجل Apidog وفروعه
مزامنة Git ثنائية الاتجاه نعم: GitHub، GitLab، Azure DevOps عبر التصدير/الاستيراد
الأفضل لـ الفرق التي تعتمد على Git في المراجعة والإصدار الفرق التي تفضل التصميم المرئي

اختر Spec-First إذا كان فريقك يراجع كل شيء عبر Pull Requests ويحتاج إلى ملفات OpenAPI داخل المستودع. اختر Design-First إذا كان فريقك يفضل واجهة مرئية ولا يعمل مباشرة على YAML أو JSON.

متى تستخدم وضع Spec-First

استخدم وضع Spec-First عندما:

  • تريد أن تمر مواصفات API عبر Pull Requests.
  • تحتاج إلى git blame وسجل commits لعقد API.
  • يشغّل CI لديك linting أو contract tests أو code generation.
  • يعمل عدة مهندسين على نفس المواصفات وتحتاج إلى diffs قابلة للمراجعة.
  • تريد إلغاء خطوة التصدير من أداة إلى أخرى.

مثال على CI بسيط لفحص المواصفات:

name: OpenAPI Check

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  lint-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint OpenAPI
        run: npx @redocly/cli lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

بهذا الشكل، أي تغيير في العقد يتم فحصه قبل الدمج.

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

ما هو سير عمل API الأصلي لـ Git؟

هو سير عمل يخزن مواصفات OpenAPI كملف داخل مستودع Git، ويدير كل تغيير عبر commits وbranches وPull Requests. تتبع المواصفات نفس عملية المراجعة والتحكم في الإصدار مثل كود التطبيق.

هل يدعم Apidog Spec-First Mode GitHub وGitLab؟

نعم. يقوم وضع Spec-First بالمزامنة ثنائيًا مع GitHub وGitLab مباشرة. كما يدعم Azure DevOps عبر اتصال Git. تختار المستودع والفرع، ثم يحافظ Apidog على مزامنة تعديلاتك مع البعيد.

هل يمكنني تحرير ملفات OpenAPI كـ YAML أو JSON خام؟

نعم. يوفر وضع Spec-First محررًا بأسلوب IDE لملفات YAML وJSON الخام، مع تمييز بناء الجملة، والتحقق من صحة المخطط، والإكمال التلقائي لـ OpenAPI وSwagger.

ما الفرق بين وضع Spec-First وDesign-First؟

يحافظ وضع Spec-First على المواصفات كملفات داخل Git ويحررها في محرر أكواد مع مزامنة ثنائية الاتجاه. يحافظ وضع Design-First على المواصفات داخل مشروع Apidog السحابي مع محرر مرئي يعتمد على النماذج.

الخاتمة

سير عمل API الأصلي لـ Git يزيل الانقسام بين الكود وعقد API. تصبح المواصفات ملفًا، والملف commit، والـ commit يمر عبر نفس عملية المراجعة التي يستخدمها فريقك بالفعل.

يمنحك Apidog Spec-First Mode طريقة عملية لتنفيذ ذلك: تحرير YAML أو JSON خام، مراجعة الفروقات، كتابة رسالة commit واضحة، الدفع إلى Git، ثم متابعة الحالة حتى تتم المزامنة.

جرّب وضع Spec-First وأعد مواصفات API الخاصة بك إلى Git.

Top comments (0)