ما هو وضع المواصفات أولاً في Apidog؟

وضع Apidog Spec-First هو مساحة عمل تجريبية مصممة للفرق التي تتعامل مع مواصفات OpenAPI الخاصة بها كشفرة مصدر. يمكنك كتابة المواصفات مباشرة بصيغة YAML أو JSON في محرر يشبه بيئة التطوير المتكاملة (IDE)، ثم مزامنتها في كلا الاتجاهين مع مستودع Git متصل. لا يوجد محرر قائم على النماذج بينك وبين الملف. المواصفات هي المشروع. إذا كنت قد أردت يومًا تعديل openapi.yaml في محرر تعليمات برمجية حقيقي ودفعه إلى GitHub دون مغادرة أداة API الخاصة بك، فهذا هو الوضع المناسب لك.

هذا الدليل هو المرجع الكامل للوضع نفسه. يغطي كل الإمكانيات، والإعداد الكامل خطوة بخطوة، ومن هو موجه إليه، والقيود المتوقعة من نسخة تجريبية (بيتا)، والأسئلة الشائعة العملية. للحصول على الفكرة الأوسع وراء هذا النهج، راجع سير عمل API الأصيل لـ Git الخاص بنا.

ما هو وضع Apidog Spec-First؟

وضع Spec-First هو وضع تحرير تجريبي في Apidog حيث يعيش تصميم واجهة برمجة التطبيقات (API) الخاصة بك كوثيقة OpenAPI خام. يمكنك فتح الملف، وتعديل YAML أو JSON، والتحقق من صحته، ثم تأكيده ودفعه إلى Git. يحافظ Apidog على مزامنة المواصفات والمستودع في كلا الاتجاهين. اسحب تغيير زميل في الفريق وسيتحدث المحرر الخاص بك. ادفع تعديلك وسيتحدث المستودع.

إنه مصمم خصيصًا لنوع واحد من الفرق: الأشخاص الذين يديرون بالفعل سير عمل Git الأصيل. سيشعر مهندسو الواجهة الخلفية، وفرق المنصات، والشركات التي تعتمد على واجهة برمجة التطبيقات (API-first) والتي تقوم بإصدار عقودها في طلبات السحب، وكأنهم في منزلهم. يصبح ملف المواصفات هو المصدر الوحيد للحقيقة، ويتولى Git معالجة التاريخ والمراجعة والفروع بالطريقة التي يفعلها لبقية قاعدة التعليمات البرمجية الخاصة بك.

هذا يختلف عن طريقة عمل معظم أدوات API. تخفي معظم الأدوات المواصفات وراء شكل رسومي. وضع Spec-First يعرض لك الملف.

وضع Spec-First مقابل وضع Design-First: نظرة سريعة

يقدم Apidog وضعين. وضع Design-First هو المحرر المرئي القائم على النماذج الذي تبدأ به معظم الفرق. وضع Spec-First هو نهج محرر التعليمات البرمجية الذي يغطيه هذا الدليل. إليك النسخة المختصرة. للحصول على تحليل كامل للمقايضات، اقرأ مقارنتنا بين Spec-First و Design-First.

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

الميزات الرئيسية

وضع Spec-First هو أكثر من مجرد مربع نص. فهو يجمع بين محرر، وملاح، وتكامل Git، وعناصر تحكم الفريق. إليك كل قدرة بالتفصيل.

محرر OpenAPI بأسلوب IDE

مركز مساحة العمل هو محرر تعليمات برمجية كامل لوثيقة OpenAPI الخاصة بك. يمكنك تعديل YAML أو JSON الخام مباشرة. يتصرف مثل المحرر الذي تستخدمه يوميًا بالفعل.

تحصل على تمييز بناء الجملة الذي يلون المفاتيح والقيم والبنية بحيث يظل الملف قابلاً للقراءة على نطاق واسع. تحصل على التحقق من صحة المخطط الذي يشير إلى الأخطاء مقابل مواصفات OpenAPI أثناء الكتابة، بحيث يظهر كائن استجابة مشوه أو حقل مطلوب مفقود على الفور. تحصل على إكمال تلقائي مُعد خصيصًا لـ OpenAPI و Swagger، والذي يقترح كلمات مفتاحية وأسماء حقول وبنية صالحة أثناء الكتابة.

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

جزء صغير مما ستعدله:

paths:
 /users/{userId}:
 get:
 summary: Get a user by ID
 operationId: getUserById
 parameters:
 - name: userId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: A single user
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/User'

مخطط تفصيلي قابل للتنقل ومحلل تلقائيًا

يصبح ملف المواصفات الخام طويلًا بسرعة. يمكن أن تصل واجهة برمجة تطبيقات حقيقية إلى آلاف الأسطر. يحل وضع Spec-First ذلك باستخدام شريط جانبي أيسر يحلل الملف تلقائيًا إلى مخطط تفصيلي مرئي.

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

هذا يحافظ على ملف openapi.yaml الكبير قابلاً للإدارة. أنت تفكر من حيث "عملية POST /orders"، وليس "السطر 1,847".

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

هذا هو جوهر الوضع. يتصل وضع Spec-First بمستودع Git الخاص بك ويقوم بمزامنة المواصفات في كلا الاتجاهين.

يتم دعم GitHub و GitLab مباشرة. يعمل Azure DevOps من خلال اتصال Git عام، والذي يتيح لك توجيه Apidog إلى المستودع باستخدام بيانات اعتماد Git القياسية. بمجرد الاتصال، يؤدي السحب إلى جلب تغييرات المستودع إلى محرر التعليمات البرمجية الخاص بك، ويرسل الدفع تعديلاتك مرة أخرى إلى المستودع. تظل المواصفات متناسقة بين جميع أعضاء الفريق لأن Git هو العمود الفقري المشترك.

إذا كنت تريد دليلاً مركزًا وخطوة بخطوة لموفر واحد، فإن دليلنا لمزامنة مواصفات OpenAPI مع GitHub يشرح هذا السير العملي بالتحديد.

التأكيد (Commit)، الدفع (Push)، ومؤشر حالة المزامنة

أنت لا تحفظ وتأمل فقط. يتبع وضع Spec-First نموذج Git الذي تعرفه بالفعل. عندما تنتهي من التعديل، تكتب رسالة تأكيد (commit message) وتؤكد التغيير. ثم تدفعه إلى المستودع المتصل.

يبقيك مؤشر حالة المزامنة على اطلاع طوال الوقت. يعرض حالات مثل "تمت المزامنة الآن" عندما تتطابق المواصفات المحلية الخاصة بك مع المستودع، ويتغير عندما يكون لديك عمل لم يتم دفعه بعد. أنت تعرف دائمًا ما إذا كانت النسخة التي أمامك هي النسخة التي يراها زملاؤك. لا تخمين، ولا مواصفات قديمة.

تتبع تغييرات الملفات

قبل أن تؤكد (commit)، يعرض لك وضع Spec-First بالضبط ما تغير. يتتبع التعديلات على مستوى الملف ويضع علامة على كل إدخال كـ معدل (modified)، أو مضاف (added)، أو محذوف (deleted). تراجع مجموعة التغييرات بالطريقة التي تراجع بها إخراج حالة Git.

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

المشاريع المحددة بالفرع والمستودع مع أذونات الفريق

مشروع Spec-First ليس عائمًا في الفراغ. تقوم بإنشائه من مستودع معين وفرع معين، وعادة ما يكون main. هذا التحديد للنطاق يعني أن المشروع يشير دائمًا إلى مكان حقيقي في Git. تتوافق مواصفاتك وتاريخك وفرعك.

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

كيفية إعداد وضع Spec-First

الإعداد هو تدفق قصير وخطي. اتبع هذه الخطوات. يتوفر الشرح الرسمي على docs.apidog.com/spec-first-mode-beta-2058268m0 إذا كنت تريد لقطات شاشة بجانبه.

1. بدّل الوضع. افتح وحدة واجهات برمجة التطبيقات (APIs) في Apidog. ابحث عن زر تبديل الوضع في الجزء السفلي الأيسر من الوحدة وبدّل من وضع Design-First إلى وضع Spec-First.
2. اربط موفر Git الخاص بك. قم بتفويض GitHub أو GitLab مباشرة. بالنسبة لـ Azure DevOps، قم بإعداد اتصال Git عام باستخدام بيانات اعتماد Git الخاصة بك.
3. أنشئ مشروعًا من مستودعك. اختر المستودع الذي يحتوي على مواصفاتك وحدد الفرع، وعادة ما يكون main. يقوم Apidog بتحديد نطاق المشروع الجديد لهذا المستودع والفرع.
4. كوّن أذونات الفريق. أثناء الإعداد، حدد من يمكنه الوصول إلى المشروع وما يمكنه تغييره.
5. عدّل المواصفات. افتح ملف openapi.yaml أو openapi.json في المحرر بأسلوب IDE. استخدم المخطط التفصيلي على اليسار للتنقل. اعتمد على التحقق من الصحة والإكمال التلقائي أثناء الكتابة.
6. أكد تغييراتك (Commit). اكتب رسالة تأكيد واضحة. راجع التغييرات المتتبعة أولاً. تخلص من أي شيء لا تريد الاحتفاظ به.
7. ادفع إلى المستودع (Push). ادفع تأكيدك إلى الفرع المتصل.
8. تحقق من المزامنة. تحقق من مؤشر حالة المزامنة. عندما يظهر "تمت المزامنة الآن"، تكون مواصفاتك ومستودعك متطابقين.

هذه هي الدورة الكاملة: تبديل، ربط، إنشاء، تعديل، تأكيد، دفع، تحقق.

سير عمل يومي نموذجي

إليك كيف يبدو الوضع عمليًا بمجرد إعداده.

تبدأ يومك بسحب أحدث التغييرات من الفرع المتصل، بحيث يعكس محرر التعليمات البرمجية الخاص بك ما قام زملاؤك بدمجه خلال الليل. تفتح المخطط التفصيلي، وتنقر على العملية التي تعمل عليها، وتبدأ في تعديل YAML. تتطلب نقطة نهاية جديدة (endpoint) نص طلب (request body)، لذا تقوم بتعريف مخطط (schema). يساعدك الإكمال التلقائي في الحصول على أسماء الحقول بشكل صحيح، ويكتشف التحقق من الصحة خطأ مطبعيًا في $ref قبل أن يصبح مشكلة.

عندما تبدو نقطة النهاية (endpoint) جيدة، تتحقق من تتبع تغييرات الملف. يظهر لك تعديلاتك. تكتب رسالة تأكيد (commit message) مثل Add POST /invoices endpoint، وتؤكد (commit)، وتدفع (push). يتحول مؤشر الحالة إلى "تمت المزامنة الآن". يراجع زميل في الفريق التغيير في طلب سحب عادي، لأن المواصفات تعيش في Git مثل أي شيء آخر.

إليك نوع الإضافة التي ستقوم بها في هذا السير العملي:

components:
 schemas:
 Invoice:
 type: object
 required: [id, amount, currency]
 properties:
 id:
 type: string
 format: uuid
 amount:
 type: integer
 description: Amount in the smallest currency unit
 currency:
 type: string
 example: USD
 status:
 type: string
 enum: [draft, sent, paid]

تبقى الدورة بأكملها داخل الأدوات التي تثق بها. المواصفات هي شفرة، وأنت تتعامل معها كشفرة.

من يجب عليه استخدام وضع Spec-First

يناسب وضع Spec-First بعض الفرق بشكل أفضل من غيرها. كن صريحًا بشأن أي نوع من الفرق أنت.

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

اختر وضع Design-First بدلاً من ذلك إذا كنت تريد تجربة بصرية موجهة. ستتحرك الفرق التي يساهم فيها غير المهندسين في التصميم، أو أي شخص يفضل النقر عبر النماذج بدلاً من كتابة YAML، بشكل أسرع هناك. غالبًا ما تفضل الفرق المختلطة حيث يشارك المنتج والتصميم في نقاط النهاية المحرر المرئي. لا توجد إجابة خاطئة. اختر الوضع الذي يتناسب مع طريقة عمل فريقك الفعلية. يتعمق منشور المقارنة الخاص بنا في هذا القرار.

القيود وملاحظات النسخة التجريبية (بيتا)

وضع Spec-First هو نسخة تجريبية (بيتا). هذه الكلمة تحمل معنى حقيقيًا، لذا اضبط توقعاتك وفقًا لذلك.

بصفته نسخة تجريبية (بيتا)، لا يزال الوضع قيد النضج. يمكن أن تتغير الإمكانيات والسلوك مع قيام Apidog بتحسين الوضع بناءً على الملاحظات. يغطي التكامل المباشر للموفر GitHub و GitLab اليوم، بينما يعتمد Azure DevOps على اتصال Git العام بدلاً من تكامل مخصص. إذا كان فريقك يعتمد على موفر Git أو سير عمل معين، فتأكد من أنه يلبي احتياجاتك قبل الالتزام بمشروع حرج في هذا الوضع.

نظرًا لأن المواصفات تتم مزامنتها مع مستودع مباشر، تنطبق قواعد Git المعتادة. قم بالتأكيد (commit) بتعمد، وادفع (push) بقصد، واستخدم خيار التخلص عندما لا يجب نشر تعديل ما. إن تتبع تغييرات الملفات ومؤشر المزامنة موجودان للحفاظ على سلامتك، ولكن مسؤولية الحفاظ على سجل نظيف لا تزال عليك. تعامل مع النسخة التجريبية (بيتا) بالطريقة التي تتعامل بها مع أي أداة جديدة تلامس فرعك الرئيسي: جربها على مستودع غير حرج أولاً، ثم قم بالتوسع بمجرد أن تثق في سير العمل.

الفائدة من النسخة التجريبية (بيتا) هي التأثير. تشكل الملاحظات المبكرة مسار تطوير الوضع، لذا إذا كان هناك شيء مفقود في سير عملك، فهذا يستحق الإبلاغ عنه.

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

هل وضع Spec-First مجاني؟

وضع Spec-First هو وضع تجريبي ضمن Apidog. يعتمد الوصول إليه على خطة Apidog الخاصة بك، لذا تحقق من توفر الوضع مقابل خطتك الحالية وحالة النسخة التجريبية (بيتا). نظرًا لأنه في مرحلة البيتا، فإن المسار الأبسط هو تمكينه في وحدة واجهات برمجة التطبيقات (APIs) ومعرفة ما إذا كان متاحًا لحسابك.

ما هي موفري Git المدعومون؟

يتم دعم GitHub و GitLab من خلال التكامل المباشر. يعمل Azure DevOps عبر اتصال Git عام، والذي يستخدم بيانات اعتماد Git القياسية لتوجيه Apidog إلى مستودعك. قد تعمل مضيفات Git الأخرى أيضًا من خلال هذا الاتصال العام، نظرًا لأنه يعتمد على Git القياسي بدلاً من واجهة برمجة تطبيقات خاصة بموفر معين.

هل يمكنني التبديل مرة أخرى إلى وضع Design-First؟

نعم. يوجد زر تبديل الوضع في الجزء السفلي الأيسر من وحدة واجهات برمجة التطبيقات (APIs)، ويمكنك التبديل بين وضع Spec-First و Design-First هناك. أنت لست مقيدًا. اختر الوضع الذي يناسب المشروع الذي تعمل عليه.

ما هي تنسيقات الملفات التي يمكنني تعديلها؟

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

ماذا يحدث لتعديلاتي غير المدفوعة؟

تبقى التعديلات غير المدفوعة محلية حتى تقوم بدفعها. يتتبع وضع Spec-First كل تغيير كـ معدل (modified)، أو مضاف (added)، أو محذوف (deleted)، ويظهر مؤشر المزامنة عندما يكون لديك عمل لم يصل إلى المستودع. إذا قررت التراجع عن تغيير، فتخلص منه قبل الدفع ولن يدخل سجل تاريخك المشترك أبدًا.

الخاتمة

يجمع وضع Apidog Spec-First محرر OpenAPI و Git معًا في مكان واحد. يمكنك تعديل المواصفات بصيغة YAML أو JSON، والتنقل فيها من خلال مخطط تفصيلي محلل تلقائيًا، والتحقق من صحتها أثناء الكتابة، والمزامنة في كلا الاتجاهين مع GitHub، GitLab، أو Azure DevOps. تمنحك رسائل التأكيد (Commit messages)، والدفع (push)، وتتبع التغييرات، ومؤشر المزامنة الواضح، سير عمل Git الذي تعرفه بالفعل، مطبقًا على عقد API الخاص بك.

إنه إصدار تجريبي (بيتا)، وهو موجه للفرق الأصلية لـ Git التي ترغب في أن تكون المواصفات شفرة مصدر. إذا كنت من هؤلاء، فإن هذا الوضع يستحق نظرة جادة. قم بتمكينه في وحدة واجهات برمجة التطبيقات (APIs)، وربط مستودعًا، وجرب دورة تعديل-تأكيد-دفع صغيرة لتشعر بسير العمل. عندما تكون جاهزًا، جرب وضع Spec-First في الوثائق وربطه بمستودع تثق به.