DEV Community

Cover image for ماذا يعني التعامل مع مواصفات API الخاصة بك ككود؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

ماذا يعني التعامل مع مواصفات API الخاصة بك ككود؟

#api #devops #git #tutorial

ربما يعيش عقد واجهة برمجة التطبيقات (API) لديك في ثلاثة أماكن في الوقت نفسه: رسم في الويكي، مجموعة Postman قديمة، ومستند Markdown يدوي لم يعد يطابق الخدمة الفعلية. عندما تختلف هذه المصادر، يبدأ الفريق بالتخمين. والتخمين يكسر التكاملات.

جرّب Apidog اليوم

الحل العملي هو التعامل مع مواصفات API كتعليمات برمجية. اكتب ملف OpenAPI واحدًا، ضعه في Git، راجعه عبر Pull Requests، ثم أنشئ منه النماذج الوهمية، الاختبارات، الوثائق، وSDKs. بهذه الطريقة تصبح المواصفات عقدًا قابلًا للمراجعة والتنفيذ، وليس مستندًا منفصلًا عن الكود.

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

ماذا تعني "المواصفات كتعليمات برمجية"

تعني أن تعريف API لديك ملف نصي عادي، عادةً openapi.yaml أو openapi.json، محفوظ داخل مستودع Git. يمكنك مراجعته، تفريعه، دمجه، تتبع تاريخه، والتراجع عنه مثل أي ملف مصدر آخر.

OpenAPI كملف داخل Git

بدل أن تكون المواصفات صفحة مستضافة أو تصديرًا من أداة، تصبح قطعة أثرية قابلة للتشغيل داخل سير العمل:

api/openapi.yaml
        ↓
mocks
        ↓
contract tests
        ↓
API docs
        ↓
SDKs
Enter fullscreen mode Exit fullscreen mode

النتيجة العملية: ملف واحد هو مصدر الحقيقة. إذا أراد مطور معرفة ما تعيده /users/{id}، يقرأ المواصفات. إذا أراد فريق QA كتابة اختبار، يبنيه على المواصفات. إذا احتاج فريق الواجهة الأمامية نموذجًا وهميًا، يتم توليده من نفس الملف.

لماذا يجب وضع المواصفات في Git

عندما تصبح المواصفات ملفًا في Git، تحصل مباشرةً على نفس آليات الحوكمة التي تستخدمها مع الكود.

1. مراجعة تغييرات API عبر Pull Requests

أي تعديل في endpoint يظهر كـ diff واضح:

  • حقل جديد في response
  • حذف حقل موجود
  • تغيير enum
  • إضافة status code
  • تعديل schema

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

2. فروقات واضحة وقابلة للقراءة

ملفات YAML تجعل التغييرات سهلة القراءة:

 status:
   type: string
-  enum: [pending, shipped, delivered]
+  enum: [pending, paid, shipped, delivered]
Enter fullscreen mode Exit fullscreen mode

هذا أفضل من تصدير غير واضح أو تغييرات داخل أداة لا تعرض تاريخًا مفصلًا.

3. إصدار وتراجع حقيقيان

يمكنك استخدام Git لإدارة دورة حياة API:

git tag api-v1.2.0
git checkout -b api-v2-redesign
git revert <commit>
Enter fullscreen mode Exit fullscreen mode

كل تغيير له مؤلف، وقت، ورسالة commit. وللتعمق أكثر في التفرع ووضع العلامات، راجع التحكم في إصدار OpenAPI باستخدام Git.

4. مصدر واحد للحقيقة

إذا كانت النماذج الوهمية، الاختبارات، الوثائق، وSDKs كلها تُنشأ من نفس ملف OpenAPI، فلن تنحرف بشكل مستقل. حدّث المواصفات، ثم أعد توليد المخرجات.

الاهتمام المواصفات في أداة مستضافة مواصفات API كتعليمات برمجية
مراجعة التغيير يدوية وسهلة التفويت Diff داخل Pull Request
التاريخ محدود أو مرتبط بالبائع سجل Git كامل
التراجع غالبًا يدوي git revert
مصدر الحقيقة غير واضح الملف الملتزم به
تكامل CI إضافة لاحقة جزء طبيعي من سير العمل

OpenAPI كقطعة أثرية قابلة للتنفيذ

OpenAPI هو التنسيق العملي الأكثر شيوعًا لأنه قابل للقراءة من البشر والآلات. احتفظ بالملف داخل المستودع، مثلًا:

api/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

مثال مختصر لملف OpenAPI 3.1:

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
            format: uuid
      responses:
        "200":
          description: The requested order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found

components:
  schemas:
    Order:
      type: object
      required:
        - id
        - status
        - total
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - shipped
            - delivered
        total:
          type: number
          format: float
Enter fullscreen mode Exit fullscreen mode

هذا الملف هو العقد. إذا أضفت حقلًا إلى Order، يظهر التغيير في PR. إذا غيّرت قيم status، يراها المراجع فورًا. وإذا كسرت التوافق العكسي، يمكن للفريق إيقاف الدمج قبل أن يصل التغيير إلى العملاء.

ما الذي يمكنك توليده من المواصفات

القيمة لا تأتي من وجود ملف OpenAPI فقط، بل من ربطه بالمخرجات اليومية للفريق.

النماذج الوهمية Mocks

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

مثال سير عمل:

1. أضف endpoint جديدًا إلى openapi.yaml
2. شغّل mock server من المواصفات
3. يستهلك فريق الواجهة الأمامية endpoint الوهمي
4. ينفذ فريق backend endpoint الحقيقي وفق العقد
Enter fullscreen mode Exit fullscreen mode

اختبارات العقد Contract Tests

أضف اختبارات تتحقق من أن الخدمة الحية تطابق المواصفات. إذا أعادت API حقلًا غير موثق أو أسقطت حقلًا مطلوبًا، يجب أن يفشل الاختبار.

مثال الفكرة:

openapi.yaml + running API → contract test → pass/fail
Enter fullscreen mode Exit fullscreen mode

الوثائق

بدل كتابة جداول endpoint يدويًا، اعرض المواصفات كوثائق مرجعية. الوثائق هنا ليست نسخة ثانية؛ هي عرض للمواصفات نفسها.

SDKs

يمكن توليد مكتبات عميل من نفس الملف. هذا مفيد عندما يكون لديك شركاء أو فرق داخلية تستهلك API بلغات مختلفة.

مخرجات متعددة من مواصفات واحدة

كيف يجعل Apidog المواصفات مصدر الحقيقة الوحيد

تشغيل هذا يدويًا يعني غالبًا ربط عدة أدوات: CLI للفحص، mock server، مولد وثائق، ومزامنة Git. Apidog يجمع هذه الأجزاء في سير عمل واحد.

في وضع Spec-First Mode، يتعامل Apidog مع ملف OpenAPI كتعريف موثوق. يمكنك تصميم endpoints بصريًا أو تحرير YAML، ثم إبقاء النماذج الوهمية، الاختبارات، والوثائق متوافقة مع نفس المواصفات.

Spec-First Mode في Apidog

الميزة العملية هنا هي مزامنة Git ثنائية الاتجاه. يمكن لـ Apidog قراءة ملف OpenAPI من المستودع وكتابة التغييرات إليه، بحيث يبقى ملف Git ومشروع Apidog متزامنين. صمّم بصريًا عندما يكون ذلك أسرع، وعدّل YAML مباشرة عندما تحتاج دقة أكبر. كلا المسارين يؤديان إلى نفس الملف الملتزم به.

لمعرفة خطوات مزامنة التغييرات مع GitHub، راجع كيفية مزامنة مواصفات OpenAPI الخاصة بك مع GitHub.

سير عمل عملي لتطبيق المواصفات كتعليمات برمجية

ابدأ بسير عمل صغير يمكن تنفيذه خلال يوم واحد.

1. ضع ملف OpenAPI في المستودع

اختر مسارًا ثابتًا:

api/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

ثم أضفه إلى Git:

git add api/openapi.yaml
git commit -m "Add OpenAPI specification"
Enter fullscreen mode Exit fullscreen mode

2. اجعل تغييرات المواصفات تمر عبر PR

لا تعدّل المواصفات خارج سير المراجعة. أي تغيير في API يجب أن يكون داخل Pull Request، بجانب الكود أو قبله.

مثال رسالة commit:

git commit -m "Add order cancellation endpoint"
Enter fullscreen mode Exit fullscreen mode

3. أضف فحص صحة المواصفات في CI

شغّل فحصًا يرفض ملفات OpenAPI غير الصالحة قبل الدمج. الفكرة الأساسية:

name: API Spec Check

on:
  pull_request:

jobs:
  lint-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate OpenAPI spec
        run: |
          echo "Run your OpenAPI lint or validation command here"
Enter fullscreen mode Exit fullscreen mode

استخدم الأداة التي تناسب فريقك، لكن اجعل الفحص إلزاميًا.

4. ولّد مخرجًا واحدًا أولًا

لا تبدأ بكل شيء مرة واحدة. اختر مخرجًا واحدًا:

  • وثائق API
  • mock server
  • contract tests
  • SDK

ابدأ بما يسبب أكبر ألم حاليًا. إذا كان فريق الواجهة الأمامية ينتظر backend كثيرًا، ابدأ بالنماذج الوهمية. إذا كانت الوثائق تنحرف، ابدأ بتوليد الوثائق.

5. أضف اختبارات عقد لاحقًا

بعد استقرار المواصفات، اربطها بالخدمة الحية. الهدف أن يفشل CI إذا لم تعد API المنشورة تطابق openapi.yaml.

المزالق الشائعة وكيف تتجنبها

الانحراف بين المواصفات والتنفيذ

كتابة المواصفات لا تكفي. إذا لم تتحقق من الخدمة الحية مقابلها، ستنحرف بمرور الوقت.

الحل:

OpenAPI spec → contract tests → CI gate
Enter fullscreen mode Exit fullscreen mode

خلط المصدر الموثوق

بعض الفرق تولّد OpenAPI من تعليقات الكود، ثم تعدّل الملف يدويًا أيضًا. هذا يخلق مصدرين للحقيقة.

اختر اتجاهًا واحدًا:

  • إما الكود يولّد المواصفات
  • أو المواصفات تقود الكود

إذا كنت تطبق spec-first، فاجعل openapi.yaml هو المصدر الموثوق.

التعامل مع المواصفات كوثائق فقط

إذا كانت المواصفات تُقرأ فقط، فهي وثيقة. إذا كانت تولّد mocks واختبارات ووثائق وSDKs، فهي عقد قابل للتنفيذ.

تخطي المراجعة

وجود الملف في Git لا يكفي. يجب أن تمر تغييرات API عبر Pull Requests ومراجعة فعلية، خصوصًا عند تغيير response schemas أو حذف حقول.

البدء

اتبع هذه الخطة المختصرة:

  1. انقل مواصفات OpenAPI إلى المستودع، مثل api/openapi.yaml.
  2. اجعل كل تغييرات المواصفات تمر عبر Pull Request.
  3. أضف فحص صحة OpenAPI في CI.
  4. ولّد مخرجًا واحدًا من المواصفات: mock أو docs أو tests.
  5. أضف اختبارات عقد تمنع الانحراف بين المواصفات والخدمة الحية.

التحول بسيط: ملف واحد في Git، يُراجع مثل الكود، وتُبنى عليه المخرجات. إذا كنت تريد تحريرًا بصريًا مع مزامنة Git، جرّب وضع Spec-First Mode في Apidog واجعل ملف OpenAPI مصدر الحقيقة الوحيد.

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

هل "مواصفات API كتعليمات برمجية" هي نفسها "وثائق كتعليمات برمجية"؟

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

ما التنسيق الأفضل لملف المواصفات؟

OpenAPI بصيغة YAML هو الخيار العملي الشائع. YAML سهل القراءة ويظهر فروقات واضحة في Pull Requests، مع بقائه قابلًا للمعالجة آليًا. JSON يعمل أيضًا، لكن YAML عادةً أوضح في المراجعة.

كيف أمنع المواصفات من الانحراف عن API الحقيقية؟

أضف اختبارات عقد إلى CI تتحقق من أن الخدمة قيد التشغيل تطابق ملف OpenAPI الملتزم به. إذا أعادت endpoint حقلًا غير معلن أو أسقطت حقلًا مطلوبًا، يجب أن يفشل البناء قبل الدمج أو النشر.

Top comments (0)