إذا كنت قد اعتمدت Bruno، فأنت تعرف بالفعل جاذبيته. تعيش مجموعاتك كملفات .bru عادية في مستودع Git الخاص بك، تحت التحكم في الإصدار جنبًا إلى جنب مع التعليمات البرمجية، دون الحاجة إلى حساب سحابي. إنه حل نظيف يعتمد على وضع عدم الاتصال أولاً لعملاء واجهة برمجة التطبيقات (API) الذين يرغبون في امتلاك بياناتك.
ولكن عاجلاً أم آجلاً، يسأل شخص ما سؤالاً لا يجيب عليه Bruno جيدًا: "أين المستندات؟ هل يمكنك إرسال رابط لي؟" هنا تواجه الفرق مشكلة. تم تصميم Bruno لإرسال الطلبات، وليس لنشر بوابة توثيق قابلة للمشاركة. يغطي هذا الدليل إنشاء توثيق واجهة برمجة تطبيقات Bruno بصدق، ما يوفره Bruno لك، وما لا يوفره، وكيفية إنشاء واستضافة المستندات من مواصفاتك عندما تحتاج إلى عنوان URL حقيقي لتقديمه للمستهلكين.
ما تحتاجه الفرق فعلاً من توثيق واجهة برمجة التطبيقات
قبل الحكم على أي أداة، من المفيد تحديد الهدف. عندما يقول الناس "توثيق واجهة برمجة التطبيقات"، فإنهم عادة ما يعنون ثلاثة أمور تعمل معًا:
- عنوان URL قابل للمشاركة. يحتاج مطورو الواجهة الأمامية والشركاء وضمان الجودة إلى قراءة المستندات دون استنساخ المستودع الخاص بك أو تثبيت عميل. يجب أن يعمل الرابط في Slack بمجرد النقر.
- مستندات تبقى متزامنة. التوثيق الذي ينحرف عن واجهة برمجة التطبيقات الحقيقية أسوأ من عدم وجوده، لأنه يرسل الأشخاص في الاتجاه الخاطئ بثقة. يجب أن تتبع المستندات المواصفات.
- تجربة "جربها" تفاعلية. قراءة أوصاف نقطة النهاية أمر جيد؛ ولكن إرسال طلب حقيقي ضد نقطة النهاية الموثقة، مع تعبئة المصادقة وحمولات العينات، هو ما يحول المستندات إلى مرجع قابل للاستخدام.
إذا حققت كل هذه الأمور الثلاثة، ستصبح مستنداتك المصدر الوحيد للمعلومات الصحيحة. وإذا فاتتك واحدة، فسيعود الناس إلى سؤالك مباشرة، وهو ما لا يمكن توسيعه.
قصة توثيق Bruno
لنكن منصفين لـ Bruno، لأنه يقوم ببعض الأمور بشكل جيد هنا.
مجموعات Bruno قابلة للقراءة البشرية. تنسيق .bru هو نص عادي، لذا يمكن للمهندس الذي يتصفح المستودع فتح ملف طلب ورؤية الطريقة وعنوان URL والرؤوس والجسم. يدعم Bruno أيضًا كتلة docs لكل طلب وعرض توثيق Markdown داخل التطبيق، بحيث يمكنك إرفاق نص توضيحي يشرح ما تفعله نقطة النهاية. ولأن كل شيء موجود في Git، تتم مراجعة هذه الملاحظات في طلبات السحب مثل أي تغيير آخر. بالنسبة لفريق داخلي يعمل ضمن قاعدة الكود، هذا شكل شرعي من أشكال التوثيق.
الفجوة الحقيقية هي النشر. لا يمتلك Bruno بوابة توثيق عامة مدمجة، مستضافة، ومنشأة تلقائيًا. لا يوجد زر "نشر" يحول مجموعتك إلى موقع ويب بعنوان URL ثابت مع نطاق مخصص. عرض المستندات داخل التطبيق مرئي للأشخاص الذين قاموا بالفعل بتثبيت Bruno واستنسخوا المجموعة، وهذا هو بالضبط الجمهور الذي يحتاج إلى المستندات أقل ما يمكن.
لذلك ترتجل الفرق الحلول. تشمل الحلول الشائعة تصدير المجموعة أو ملف OpenAPI وتغذيته إلى مولد مستندات ثابت منفصل، أو إعداد موقع مستندات في CI، أو الاحتفاظ بملف README مكتوب يدويًا يقوم شخص ما بتحديثه بالذاكرة. يمكن أن تنجح هذه الطرق، ولكنها تضيف مسار بناء يجب صيانته ومكانًا ثانيًا حيث يمكن أن تتغير المعلومات. لم يعد التوثيق ناتجًا أساسيًا للأداة التي تختبرها؛ بل أصبح مشروعًا جانبيًا.
مبدأ المستندات كتعليمات برمجية
الطريقة الأنظف للتفكير في هذا، وهي ما يؤمن به مستخدمو Bruno جزئيًا بالفعل: عامل توثيقك كناتج لمواصفاتك، وليس قطعة أثرية منفصلة.
في سير عمل المستندات كتعليمات برمجية، يتم وصف واجهة برمجة التطبيقات الخاصة بك مرة واحدة في مواصفات قابلة للقراءة آليًا، وعادة ما تكون OpenAPI. تعيش تلك المواصفات في Git، وتتم مراجعتها في طلبات السحب، وتعمل كعقد. يتم إنشاء التوثيق والخوادم الوهمية وحزم SDK للعملاء جميعًا منها. عندما يتغير العقد، تتم مراجعة التغيير في مكان واحد، ويتبعه كل ما هو لاحق.
الميزة هي أنه لا توجد مهمة منفصلة "لتحديث المستندات" لتنساها. المستندات هي عرض للمواصفات. إذا كانت المواصفات صحيحة وتمت مراجعتها، فالمستندات صحيحة. هذا هو المبدأ الذي يشير إليه Bruno من خلال الاحتفاظ بالمجموعات في Git، لكنه يتوقف قبل خطوة النشر.
أنشئ واستضف المستندات من مواصفاتك بدلاً من ذلك
هذه هي الفجوة التي تم بناء Apidog لسدها. يحتفظ Apidog بنفس النموذج الذهني المتمحور حول المواصفات والملائم لـ Git، ثم يضيف الجزء الذي تركه Bruno: يقوم بإنشاء موقع توثيق تفاعلي ومستضاف مباشرة من مواصفاتك، دون الحاجة إلى مسار بناء منفصل.
وجّه Apidog إلى مواصفات OpenAPI الخاصة بك وسينتج بوابة توثيق تلقائيًا. والنتيجة هي:
- مستضافة على عنوان URL قابل للمشاركة، بحيث يمكن لأي شخص لديه الرابط قراءة المستندات دون تثبيت أي شيء.
- يمكن تثبيتها على نطاق مخصص، بحيث يمكن أن تعيش المستندات على
docs.yourcompany.comوتتوافق مع علامتك التجارية. - تفاعلية، مع لوحة "جربها" مدمجة ترسل طلبات حقيقية باستخدام المعلمات والرؤوس والمصادقة الموثقة.
- مُنشأة من المواصفات، لذا تعكس المستندات ما تعلنه واجهة برمجة التطبيقات فعليًا بدلاً من نسخة مكتوبة يدويًا يمكن أن تنحرف.
لأن نفس المواصفات تدفع أيضًا اختبار Apidog والمحاكاة، فأنت لا تحتفظ بثلاثة أوصاف لواجهة برمجة تطبيقات واحدة. تصفها مرة واحدة وتعيد استخدامها.
دليل إرشادي: من المواصفات إلى عنوان URL قابل للمشاركة
إليك النسخة المختصرة لنشر المستندات من مواصفات OpenAPI.
| الخطوة | الإجراء | النتيجة |
|---|---|---|
| 1 | استورد أو اكتب مواصفات OpenAPI الخاصة بك في Apidog | تُملأ نقاط النهاية والمخططات والأمثلة تلقائيًا |
| 2 | افتح إعدادات توثيق المشروع | تُنشأ المستندات من المواصفات، جاهزة للتكوين |
| 3 | اختر مستوى الرؤية و(اختياريًا) نطاقًا مخصصًا | تكون المستندات عامة أو خاصة أو محمية بكلمة مرور |
| 4 | انشر | يتم إنشاء موقع مستندات مباشر ومستضاف بعنوان URL ثابت |
| 5 | شارك الرابط | يقرأ المستهلكون المستندات ويجرون طلبات "جربها" |
إذا كان لديك بالفعل مجموعة Bruno، يمكنك تحويلها إلى OpenAPI أولاً، ثم استيراد تلك المواصفات. من هناك، خطوة النشر هي نفسها. النقطة هي أن إنشاء واستضافة المستندات أمر أساسي، وليس مسارًا تقوم بتجميعه بنفسك.
الحفاظ على تزامن المستندات مع تغير المواصفات
لا يكون عنوان URL للمستندات مفيدًا إلا إذا ظل دقيقًا. نمط الفشل في الإعدادات المرتجلة هو أن يقوم شخص ما بنشر تغيير في نقطة النهاية وينسى المستندات.
عندما تُنشأ المستندات من المواصفات، يتقلص هذا الخطر. تقوم بتحرير المواصفات، ويمر تغيير المواصفات بالمراجعة مثل أي تغيير آخر في التعليمات البرمجية، وتعكس المستندات المنشورة الحالة الجديدة. لا يوجد مستند موازٍ لتذكره. أضف حقلًا إلى مخطط استجابة وسيظهر في المستندات؛ أوقف نقطة نهاية وستذكر المستندات ذلك. العمل الذي تقوم به بالفعل للحفاظ على صحة العقد هو نفس العمل الذي يحافظ على صحة المستندات.
هذه هي الفائدة العملية لمبدأ المستندات كتعليمات برمجية: تصبح الدقة أثرًا جانبيًا لسير عمل ترغب فيه على أي حال، بدلاً من مهمة منفصلة تعتمد على الانضباط.
الأسئلة الشائعة
هل يمكن لـ Bruno إنشاء واستضافة توثيق واجهة برمجة تطبيقات عامة؟
يوفر Bruno ملفات مجموعات .bru قابلة للقراءة وعرض توثيق Markdown داخل التطبيق، وكلاهما يُراجع في Git. لا يتضمن بوابة توثيق عامة مدمجة، مستضافة، ومنشأة تلقائيًا مع عنوان URL قابل للمشاركة. لنشر المستندات العامة من Bruno، عادة ما تصدر الفرق مواصفات وتشغل مولد مستندات ثابت منفصل، مما يضيف مسار عمل للصيانة.
كيف أحصل على عنوان URL قابل للمشاركة للمستندات من واجهة برمجة التطبيقات الخاصة بي؟
صف واجهة برمجة التطبيقات الخاصة بك في مواصفات OpenAPI، ثم استخدم أداة تنشئ مستندات مستضافة منها. في Apidog، تقوم باستيراد المواصفات، وتكوين مستوى الرؤية، وإرفاق نطاق مخصص اختياريًا، ثم النشر. الناتج هو موقع توثيق مباشر على عنوان URL ثابت، مع لوحة "جربها" تفاعلية، يمكنك مشاركتها مباشرة.
هل يجب أن أتخلى عن مجموعات Bruno الخاصة بي لنشر المستندات؟
لا. يمكنك تحويل مجموعة Bruno موجودة إلى OpenAPI واستيراد تلك المواصفات إلى أداة توثيق. تنتقل نقاط النهاية والمخططات والأمثلة الخاصة بك، وتحتفظ بالمواصفات تحت التحكم في الإصدار. يتم الانتقال على طبقة المواصفات، لذلك لا تزال عادات "المستندات كتعليمات برمجية" التي بنيتها باستخدام Bruno سارية.