العقود

يصف العقد ما تقبله واجهة API وما تعيده. يبنيه Getman من الطلبات المحفوظة، ويصدّره بصيغة OpenAPI 3.1، ويقارن نسختين ليوضح ما الذي يكسره تغيير ما. يعيش العقد الحالي للفريق في contracts/openapi.yaml داخل مساحة العمل، وتُفحص حزم التغيير في مقابله.

تصدير عقد

1. افتح قائمة المشروع في شريط العنوان واختر Export project…. يمكنك أيضا تشغيل Export OpenAPI contract… من لوحة الأوامر (⌘K).
2. اختر OpenAPI 3.1 واحفظ الملف.

التصدير حتمي: المشروع نفسه يعطي الملف نفسه دائما، مع ترتيب المفاتيح والمسارات. تُزال القيم السرية وأسرار العميل والمتغيرات السرية قبل التصدير، ولا تُحفظ إلا أسماء مخططات المصادقة.

كيف تتحول الطلبات إلى عمليات

في Getman	في OpenAPI 3.1
{{base_url}} في بداية العنوان	خادم، والقيمة الافتراضية من البيئة عندما لا تكون القيمة سرية
:id أو {{id}} في المسار	معامل مسار مطلوب باسم {id}
اسم الطلب	summary
معاملات الاستعلام والترويسات المفعّلة	معاملات مع required: false
جسم JSON	application/json مع مخطط مستنتج من الجسم
أمثلة الاستجابة	استجابة واحدة لكل حالة، مع أمثلة
طلبات تشترك في الطريقة والمسار نفسيهما	عملية واحدة. تُدمج أمثلة استجابات جميعها
المصادقة	مخططات أمان، وعنصر security لكل عملية

تُستنتج المخططات من الأمثلة المحفوظة، فهي نقطة بداية وليست مواصفة نهائية. تصبح كل خاصية في مثال واحد مطلوبة. يُصنَّف التغيير الذي يعتمد على مخطط مستنتج على أنه potentially breaking لا breaking، لذلك راجع المخطط المستنتج قبل الاعتماد عليه.

مقارنة عقدين

1. افتح لوحة الأوامر (⌘K) واختر Compare API contracts…. تفتح عرض Compare contracts.
2. لكل جانب، اختر This project لاستخدام الطلبات الحالية للمشروع، أو OpenAPI file ثم Choose file…. يمكن أن يبقى جانب واحد على هذا المشروع.
3. اقرأ الفرق. يسرد كل تغيير مع عمليته، ويمكنك التصفية حسب الخطورة أو الجانب (الطلب أو الاستجابة).
4. يعرض كل تغيير قيمه قبل وبعد. وينسخ Copy as text الفرق كاملا.

لكل تغيير خطورة، تُعطى بشكل منفصل لجانب الطلب ولجانب الاستجابة:

الخطورة	المعنى
Breaking	يفشل العملاء الحاليون
Potentially breaking	قد يفشل بعض العملاء، بحسب طريقة استخدامهم للحقل
Non-breaking	يستمر العملاء الحاليون في العمل
Unknown	لا يمكن تصنيف التغيير، غالبا لأن مخططا مفقود في أحد الجانبين

تأتي القواعد من 43 نوعا من التغييرات. أمثلة قليلة:

التغيير	جانب الطلب	جانب الاستجابة
إضافة نقطة نهاية	Non-breaking	Non-breaking
حذف نقطة نهاية	Breaking	Breaking
إضافة معامل مطلوب	Breaking	لا ينطبق
إضافة معامل اختياري	Non-breaking	لا ينطبق
حذف حالة استجابة	لا ينطبق	Breaking
إضافة حالة استجابة	لا ينطبق	Potentially breaking
إضافة خاصية مطلوبة إلى طلب	Breaking	Non-breaking
حذف خاصية من استجابة	لا ينطبق	Breaking
حذف قيمة من enum في طلب	Breaking	Non-breaking

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

تصميم واجهة API

API design مستند OpenAPI 3.1 قابل للتحرير للمشروع. افتحه من الشريط، أو من Open API design في لوحة الأوامر.

• يبني Generate التصميم من الطلبات المحفوظة.
• يضيف Merge العمليات التي لا يملكها التصميم، ولا يغيّر العمليات الموجودة أبدا.
• يقرأ Import ملفات OpenAPI 3.0 أو 3.1، بصيغة JSON أو YAML. يُرفض Swagger 2.0، لذلك حوّله أولا.
• يحوّل Create requests التصميم إلى مجموعة جديدة، ويُحفظ base_url الخاص بالمشروع.
• يقارن Compare التصميم بطلباتك.

يُحفظ التصميم داخل التطبيق، ولا يُكتب أبدا إلى contracts/openapi.yaml. يبقى هذا الملف آخر عقد منشور حتى تصدّر من جديد.

القيود

• تُصدَّر المعاملات كنصوص، لأن Getman يخزن قيم المعاملات كنص.
• لا تُقارَن readOnly وwriteOnly والأوصاف والقيم الافتراضية والأمثلة.
• تُقارَن oneOf وanyOf ككل، لذلك تكون الخطورة Unknown.
• لا تُصدَّر callbacks وwebhooks وlinks ومعاملات الكوكيز.
• القيمة الافتراضية لـ info.version في التصدير هي 1.0.0، لأن المشروع لا يملك حقل إصدار للواجهة.
• في التصميم، تُحرَّر allOf وoneOf وanyOf في لسان JSON، لا في نموذج المخطط.

الخطوات التالية

• تشرح Git والتعاون كيف ينتقل العقد مع مساحة عمل الفريق.
• يعرض سير عمل الفريق حزمة تغيير تُفحص في مقابل العقد.