إذا كنت تستخدم Bruno، فأنت تستفيد غالبًا من أهم ميزاته: مجموعات API محفوظة كملفات .bru داخل مستودع Git، قابلة للمراجعة مع الكود، وتعمل بدون حساب سحابي. هذا ممتاز للاختبار الداخلي والعمل بأسلوب offline-first، لكنه لا يحل دائمًا مشكلة نشر توثيق API قابل للمشاركة مع الفريق أو العملاء.
السؤال العملي الذي يظهر لاحقًا هو: كيف أرسل رابطًا للتوثيق؟
Bruno يساعدك على تنظيم الطلبات وتشغيلها، لكنه لا يوفر بوابة توثيق عامة مستضافة تلقائيًا. في هذا الدليل سنحدد ما الذي يقدمه Bruno فعلًا، أين تظهر الفجوة، وكيف تنشئ توثيق API قابلًا للنشر من مواصفات OpenAPI باستخدام سير عمل أكثر قابلية للتنفيذ.
ما الذي تحتاجه الفرق فعليًا من توثيق API؟
قبل اختيار الأداة، حدّد متطلبات التوثيق. في أغلب فرق التطوير، التوثيق الجيد يحتاج إلى ثلاثة عناصر:
- رابط قابل للمشاركة: يجب أن يستطيع مطورو الواجهة الأمامية، QA، الشركاء، أو العملاء فتح التوثيق من المتصفح بدون تثبيت Bruno أو استنساخ المستودع.
- مزامنة مع العقد الحقيقي للـ API: إذا تغيرت نقطة نهاية أو مخطط استجابة، يجب أن ينعكس ذلك في التوثيق. التوثيق غير المتزامن يسبب أخطاء أكثر مما يحل.
- تجربة تفاعلية: من الأفضل أن يستطيع المستخدم إرسال طلب مباشر من صفحة التوثيق عبر لوحة “جرّبها”، مع المعلمات والرؤوس والمصادقة والأمثلة.
إذا كان التوثيق يفتقد أحد هذه العناصر، سيعود المطورون غالبًا إلى سؤال الفريق مباشرة بدل الاعتماد على المستندات.
ماذا يوفر Bruno للتوثيق؟
Bruno يقدم أساسًا جيدًا للتوثيق الداخلي:
- ملفات
.bruنصية وقابلة للقراءة. - يمكن حفظها داخل Git.
- يمكن مراجعة تغييرات الطلبات في Pull Requests.
- يدعم Bruno كتلة
docsلكل طلب. - يمكن عرض Markdown داخل التطبيق.
مثال مبسط على فكرة ملف طلب داخل Bruno:
meta {
name: Get User
type: http
}
get {
url: {{baseUrl}}/users/{{userId}}
}
headers {
Authorization: Bearer {{token}}
}
docs {
# Get User
يعيد بيانات مستخدم واحد بناءً على userId.
}
هذا مفيد جدًا لفريق داخلي يستخدم Bruno بالفعل. أي مطور داخل المستودع يستطيع فتح الملف وفهم الطلب وسياقه.
لكن المشكلة تبدأ عند الحاجة إلى نشر التوثيق خارج التطبيق.
أين تظهر فجوة Bruno؟
Bruno لا يوفر بوابة توثيق عامة مدمجة ومستضافة تلقائيًا. لا يوجد زر نشر يحوّل المجموعة إلى موقع ويب ثابت مثل:
https://docs.example.com
ولا توجد بوابة مدمجة يمكن مشاركتها مباشرة مع مستهلكي API الذين لا يستخدمون Bruno.
لذلك تلجأ الفرق عادة إلى حلول إضافية مثل:
- تصدير مجموعة Bruno أو تحويلها إلى OpenAPI.
- استخدام مولد توثيق ثابت.
- بناء موقع توثيق داخل CI/CD.
- كتابة README يدويًا.
- تحديث ملفات Markdown منفصلة بجانب الطلبات.
هذه الحلول ممكنة، لكنها تضيف مسار عمل جديدًا يجب صيانته. والأسوأ أنها تنشئ مكانًا ثانيًا يمكن أن ينحرف عن حالة API الفعلية.
استخدم مبدأ “المستندات كتعليمات برمجية”
الطريقة الأكثر استقرارًا هي التعامل مع التوثيق كناتج من مواصفات API، وليس كملف منفصل يتم تحديثه يدويًا.
في سير عمل المستندات كتعليمات برمجية، يتم وصف API مرة واحدة في مواصفات قابلة للقراءة آليًا، غالبًا OpenAPI. بعدها يمكن استخدام نفس المواصفات لإنشاء:
- التوثيق.
- الخوادم الوهمية.
- الاختبارات.
- أمثلة الطلبات.
- SDKs أو تعريفات العملاء عند الحاجة.
الفكرة العملية هي:
OpenAPI Spec
├── Documentation
├── Mock Server
├── Tests
└── Client SDKs
بدلًا من تحديث التوثيق يدويًا، يتم تحديث المواصفات. ثم تُبنى المستندات منها.
أنشئ التوثيق من OpenAPI بدلًا من الاعتماد على ملفات منفصلة
إذا كان هدفك نشر توثيق API قابل للمشاركة، فابدأ من مواصفات OpenAPI. يمكن أن تأتي هذه المواصفات من:
- مشروعك مباشرة.
- ملف OpenAPI موجود في Git.
- تصدير من أداة API.
- تحويل من مجموعة Bruno إذا كان ذلك مناسبًا لسير عملك.
هذه هي الفجوة التي تم بناء Apidog لسدها: إنشاء توثيق تفاعلي ومستضاف من المواصفات، بدون الحاجة إلى بناء مولد توثيق منفصل يدويًا.
عند استيراد مواصفات OpenAPI إلى Apidog، يمكن إنشاء بوابة توثيق تحتوي على:
- رابط مستضاف قابل للمشاركة.
- دعم نطاق مخصص مثل
docs.yourcompany.com. - لوحة “جرّبها” لإرسال طلبات فعلية.
- توثيق منشأ من المواصفات بدل محتوى يدوي منفصل.
- نفس مصدر الحقيقة المستخدم للاختبار والمحاكاة.
خطوات عملية: من OpenAPI إلى رابط توثيق قابل للمشاركة
استخدم الخطوات التالية إذا كان لديك ملف OpenAPI وتريد نشر توثيق قابل للاستخدام:
| الخطوة | الإجراء | النتيجة |
|---|---|---|
| 1 | استورد أو اكتب مواصفات OpenAPI الخاصة بك في Apidog | تُملأ نقاط النهاية والمخططات والأمثلة تلقائيًا |
| 2 | افتح إعدادات توثيق المشروع | تُنشأ المستندات من المواصفات وتصبح جاهزة للتكوين |
| 3 | اختر مستوى الرؤية و، اختياريًا، نطاقًا مخصصًا | يمكن جعل المستندات عامة أو خاصة أو محمية بكلمة مرور |
| 4 | انشر التوثيق | يتم إنشاء موقع مستندات مباشر ومستضاف بعنوان URL ثابت |
| 5 | شارك الرابط مع الفريق أو المستهلكين | يمكنهم قراءة المستندات وتجربة الطلبات من المتصفح |
مثال OpenAPI بسيط يمكن استخدامه كنقطة بداية
إذا لم تكن لديك مواصفات جاهزة، يمكنك البدء بملف صغير مثل هذا:
openapi: 3.0.3
info:
title: Users API
version: 1.0.0
servers:
- url: https://api.example.com
paths:
/users/{id}:
get:
summary: الحصول على مستخدم حسب المعرّف
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: تم العثور على المستخدم
content:
application/json:
schema:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
بعد استيراد هذا الملف، يجب أن يظهر المسار /users/{id} في التوثيق مع المعلمة id ومخطط الاستجابة.
إذا كنت تستخدم Bruno بالفعل
لا تحتاج إلى التخلي عن Bruno فورًا. يمكنك استخدامه كأداة تشغيل طلبات داخلية، ثم تحويل أو تصدير العقد إلى OpenAPI عند الحاجة إلى نشر التوثيق.
سير عمل عملي يمكن أن يبدو هكذا:
Bruno Collection
↓
OpenAPI Spec
↓
Apidog Documentation
↓
Public or Private Docs URL
النقطة المهمة هي أن النشر يجب أن يعتمد على المواصفات، وليس على README منفصل أو تحديثات يدوية متفرقة.
كيف تحافظ على تزامن التوثيق مع API؟
أكبر مشكلة في التوثيق اليدوي هي النسيان. قد يغير أحد المطورين نقطة نهاية أو يضيف حقلًا جديدًا في الاستجابة، ثم لا يتم تحديث المستندات.
لتقليل هذا الخطر:
- اجعل OpenAPI هو مصدر الحقيقة.
- خزّن المواصفات في Git.
- راجع تغييرات المواصفات في Pull Requests.
- انشر التوثيق من المواصفات نفسها.
- لا تكتب وصفًا موازيًا لنفس العقد في ملفات منفصلة إلا عند الحاجة.
مثال على تغيير يجب أن يظهر في Pull Request:
properties:
id:
type: string
name:
type: string
+ role:
+ type: string
+ enum: [admin, user]
عندما يكون التوثيق منشأ من المواصفات، فإن إضافة role إلى مخطط الاستجابة تنعكس في صفحة التوثيق بدل الحاجة إلى تحديثها يدويًا.
متى يكون Bruno كافيًا؟
Bruno مناسب إذا كان التوثيق موجهًا لفريق داخلي يستخدم نفس المستودع ونفس الأداة. مثلًا:
- فريق backend صغير.
- كل أعضاء الفريق يملكون وصولًا إلى Git.
- التوثيق المطلوب هو ملاحظات داخلية حول الطلبات.
- لا تحتاج إلى رابط عام أو بوابة مستضافة.
في هذه الحالة، ملفات .bru مع كتل docs قد تكون كافية.
متى تحتاج إلى بوابة توثيق مستضافة؟
ستحتاج إلى حل توثيق منشور عندما يكون لديك:
- فريق frontend لا يريد تثبيت عميل API.
- شركاء خارجيون يحتاجون إلى مرجع API.
- فريق QA يحتاج إلى تجربة الطلبات من المتصفح.
- عملاء يحتاجون إلى رابط مستندات.
- نطاق مخصص للتوثيق.
- حاجة إلى “جرّبها” داخل صفحة المستندات.
هنا يصبح إنشاء التوثيق من OpenAPI ونشره كعنوان URL ثابت أكثر عملية من الاعتماد على ملفات Bruno وحدها.
الأسئلة الشائعة
هل يمكن لـ Bruno إنشاء واستضافة توثيق API عام؟
يوفر Bruno ملفات .bru قابلة للقراءة، ويدعم توثيق Markdown داخل التطبيق، ويمكن حفظ كل ذلك في Git. لكنه لا يتضمن بوابة توثيق عامة مدمجة ومستضافة تلقائيًا بعنوان URL قابل للمشاركة. لنشر مستندات عامة، تحتاج عادة إلى تصدير أو تحويل المواصفات واستخدام أداة توثيق منفصلة.
كيف أحصل على رابط توثيق قابل للمشاركة؟
اكتب أو استورد مواصفات OpenAPI، ثم استخدم أداة تنشئ مستندات مستضافة منها. في Apidog، يمكنك استيراد المواصفات، ضبط مستوى الرؤية، إضافة نطاق مخصص اختياريًا، ثم نشر التوثيق للحصول على رابط ثابت.
هل يجب أن أترك Bruno لنشر المستندات؟
لا. يمكنك الاستمرار في استخدام Bruno لتشغيل الطلبات داخليًا، واستخدام OpenAPI كطبقة مواصفات للنشر. الفكرة هي أن يتم إنشاء التوثيق من العقد نفسه، سواء بدأت من Bruno أو من ملف OpenAPI مباشر.
ما أفضل مصدر حقيقة للتوثيق؟
أفضل مصدر حقيقة هو مواصفات API القابلة للمراجعة، مثل OpenAPI. إذا كانت المواصفات في Git وتخضع للمراجعة، يمكن توليد التوثيق منها باستمرار وتقليل الانحراف بين API الفعلي والمستندات.
الخلاصة
Bruno ممتاز كعميل API يعتمد على Git وملفات نصية، لكنه ليس حلًا كاملًا لنشر بوابة توثيق API عامة. إذا كان هدفك إرسال رابط مستندات قابل للمشاركة، استخدم مواصفات OpenAPI كمصدر حقيقة، ثم أنشئ التوثيق المستضاف منها.
بهذا تحصل على سير عمل أوضح:
اكتب العقد مرة واحدة → راجعه في Git → أنشئ التوثيق منه → شارك الرابط
وهذا يقلل التحديثات اليدوية، ويحافظ على دقة المستندات، ويجعل API أسهل للاستهلاك من قبل الفرق الداخلية والخارجية.
Top comments (0)