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

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

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

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

المواصفات الموجودة في Wiki أو محرك أقراص مشترك ليس لها تاريخ. لا يمكنك معرفة من قام بتغيير حمولة POST /orders الثلاثاء الماضي، أو لماذا. Git يحل ذلك.

ضع openapi.yaml تحت التحكم في الإصدار وستحصل على أربعة أشياء مجانًا:

• السجل. كل تغيير هو commit مع مؤلف، وطابع زمني، ورسالة.
• لوم. يخبرك git blame openapi.yaml من أضاف هذا الحقل المطلوب ومتى.
• الاسترجاع. دمج سيء أدى إلى كسر العقد؟ قم بإلغاء commit وستعود إلى مواصفات عمل.
• المراجعة. تمر تغييرات المواصفات عبر طلبات السحب (pull requests)، بحيث يرى شخص ثانٍ الفرق قبل أن يتم الشحن.

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

أين يعيش ملف المواصفات في المستودع؟

حافظ على البساطة والقدرة على التنبؤ. تضع معظم الفرق ملف openapi.yaml واحدًا في جذر المستودع أو في مجلد api/:

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

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

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

هذا يحافظ على التغييرات المتعارضة معزولة. يبقى api-v1.yaml ثابتًا للعملاء الحاليين بينما يتطور api-v2.yaml. كما أنه يجعل الفروقات أصغر والمراجعة أسرع، لأن كل ملف يتغير لسبب واحد. معالجة المواصفات بهذه الطريقة هي الفكرة الأساسية وراء مواصفات API كرمز.

اختر اتفاقية واحدة ووثّقها. أسوأ نتيجة هي وجود ملفين يدعيان أنهما "المواصفات".

استراتيجيات التفريع لتغييرات المواصفات

لا تحتاج إلى نموذج تفريع خاص بالمواصفات. أعد استخدام ما يفعله الكود الخاص بك بالفعل. تفرع من main، قم بإجراء التغيير، افتح طلب سحب.

اتفاقية تسمية تجعل فروع المواصفات سهلة المسح:

البادئة api/ تشير بوضوح إلى "طلب السحب هذا يمس العقد". يمكن للمراجعين و CI تصفية الطلبات بناءً عليها. بالنسبة للتغييرات المتقطعة، البادئة الصريحة breaking- هي علامة على أن هذا يتطلب اهتمامًا إضافيًا وربما زيادة في الإصدار.

اجعل الفروع قصيرة الأجل. فرع المواصفات الذي يعيش لمدة أسبوعين سيتعارض مع تغييرات الآخرين. الفروع الصغيرة والمركزة تدمج بسلاسة.

مراجعة تغييرات المواصفات في طلب سحب

هنا يكسب التحكم في الإصدار أهميته. طلب سحب للمواصفات هو تغيير عقد، وتغييرات العقد تستحق مراجعة حقيقية.

اكتب 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"

الترتيب المتناسق وحقل واحد لكل سطر يعني أن إضافة حقل واحد تظهر كفرق سطر واحد. هذا هو الهدف.

ما يجب على المراجعين التحقق منه:

• التغييرات الجوهرية. هل تمت إضافة حقل مطلوب إلى طلب؟ هل تم حذف حقل استجابة أو إعادة تسميته؟ هل فقد تعداد قيمة؟ كل واحد من هذه يمكن أن يعطل العملاء الحاليين.
• التوافق مع الإصدارات السابقة. الحقول الاختيارية الجديدة ونقاط النهاية الجديدة آمنة. التغييرات على الأشكال الموجودة ليست كذلك.
• التسمية والاتساق. هل تتطابق نقطة النهاية الجديدة مع حالة الحروف والجمع لبقية واجهة برمجة التطبيقات؟
• الكمال. تحتاج كل عملية جديدة إلى summary ومخططات استجابة واستجابات أخطاء.
• الأمثلة. الأمثلة الواقعية تجعل الوثائق والنماذج الأولية مفيدة.

لاكتشاف التغييرات الجوهرية، اعتمد على الأدوات بدلاً من الفحص البصري. يمكن لخطوة CI (المغطاة أدناه) مقارنة مواصفات طلب السحب مقابل main وفشل البناء إذا اكتشفت تغييرًا غير متوافق. البشر يفتقدون هذه؛ أدوات المقارنة لا تفعل ذلك.

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

تحرير YAML الخام يدويًا يعمل، لكن محررًا مرئيًا مع التحقق المباشر أسرع ويلتقط الأخطاء مبكرًا. يمنحك وضع Apidog's Spec-First مزامنة Git ثنائية الاتجاه: قم بتحرير المواصفات في واجهة المستخدم، وقم بالالتزام، وادفع إلى المستودع الخاص بك دون مغادرة الأداة. اسحب تغييرات زميلك بالطريقة نفسها.

يبدو التدفق كالتالي:

1. قم بتوصيل مستودع Git الخاص بك ووجه Apidog إلى ملف المواصفات.
2. قم بتحرير نقاط النهاية والمخططات والأمثلة في المحرر المرئي.
3. يكتب Apidog YAML نظيفًا وصديقًا للاختلافات مرة أخرى إلى الملف.
4. التزم على فرع وادفع، ثم افتح طلب السحب الخاص بك كالمعتاد.

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

خطافات التحقق من التكامل المستمر (CI)

لا تدع أبدًا مواصفات غير صالحة تصل إلى main. قم بربط التحقق من الصحة في فحوصات طلب السحب الخاصة بك بحيث يفشل العقد المعطل عملية البناء تلقائيًا.

خطوة بسيطة لـ GitHub Actions:

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

أضف المزيد من الفحوصات كلما تطورت:

• فحص المواصفات بحثًا عن مشكلات هيكلية وأسلوبية.
• التحقق من أنها تحلل كـ OpenAPI 3.x قانوني.
• المقارنة مع main لاكتشاف التغييرات الجوهرية والإبلاغ عنها في طلب السحب.

تستغرق هذه الفحوصات ثوانٍ وتلتقط الأخطاء التي يتجاهلها المراجع البشري.

أفضل الممارسات

بعض العادات تحافظ على صحة التحكم في إصدار المواصفات بمرور الوقت:

• استخدم الترقيم الدلالي للإصدارات. قم بزيادة حقل info.version. التغيير الجوهري يعني إصدارًا رئيسيًا جديدًا؛ الإضافات المتوافقة مع الإصدارات السابقة تزيد الإصدار الثانوي.
• احتفظ بسجل التغييرات. ملف CHANGELOG.md قصير بجانب المواصفات يخبر المستهلكين بما تغير بين الإصدارات.
• اشحن فروقات صغيرة. تغيير منطقي واحد لكل طلب سحب. طلبات السحب الكبيرة للمواصفات تخفي التغييرات الجوهرية في الضوضاء.
• اكتب رسائل التزام وصفية. "إضافة refundReason إلى طلب استرداد" أفضل من "تحديث المواصفات".
• لا تقم أبدًا بتحرير المواصفات المدمجة مباشرة على main. قم دائمًا بإنشاء فرع، حتى لإصلاح خطأ مطبعي.

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

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

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

هل يجب أن أحتفظ بملف OpenAPI واحد أم أقسمه إلى عدة ملفات؟

ابدأ بملف openapi.yaml واحد. إنه الأسهل للمراجعة والتحكم في الإصدارات. عندما يصبح الملف كبيرًا أو تحتفظ بإصدارات رئيسية متعددة بالتوازي، قم بالتقسيم حسب الإصدار الرئيسي (api-v1.yaml, api-v2.yaml) أو استخدم $ref لتقسيم المخططات إلى ملفات منفصلة. لا تقسم قبل الأوان؛ ملف واحد قابل للقراءة أفضل من خمسة ملفات مجزأة.

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

نعم. يتيح لك وضع Apidog's Spec-First تحرير المواصفات في محرر مرئي ومزامنة التغييرات مع Git في كلا الاتجاهين. يكتب YAML متناسقًا، لذا تظل فروقاتك نظيفة وتظل طلبات السحب الخاصة بك قابلة للقراءة، بينما لا تزال تحصل على سجل Git كامل ومراجعة.