# مرجع واجهة Nibleaf API وOpenAPI

> اعثر على مواصفات الخادم المستضاف ذاتيًا، وافهم المصادقة بجلسة المتصفح، وميّز واجهات API في Nibleaf من مراجع API المنشورة للعملاء.

يعرض خادم Nibleaf مرجعًا تفاعليًا مدعومًا بـOpenAPI على `/docs` في منفذ واجهة
API رقم 4311. في مكدّس التطوير، افتح `http://localhost:4311/docs`. وفي بيئة
الإنتاج، تبقى واجهة API داخلية عادةً، ويمرّر التطبيق طلبات المتصفح عبر `/api`
كي تظل ملفات تعريف ارتباط الجلسة من الطرف الأول.

## استخدام مواصفات الإصدار المطابق

مواصفات الخادم قيد التشغيل هي المصدر المرجعي لمسارات التوجيه والطرائق والمخططات ورموز
الاستجابة. لا تنشئ تكاملًا انطلاقًا من لقطة شاشة أو مواصفات أنشأها وسم صورة
مختلف.

للتطوير المحلي:

```bash
docker compose -f docker-compose.dev.yml up -d
pnpm db:generate
pnpm db:deploy
pnpm db:seed
pnpm dev
```

لا تفتح مرجع واجهة API إلا بعد تشغيل الخادم. البيانات التجريبية الأولية مخصّصة
للتطوير المحلي، ويجب عدم تفعيلها في بيئة الإنتاج.

## حدود المصادقة

تستخدم مسارات لوحة التحكم جلسة المتصفح المصادَق عليها وتفويض المؤسسة والمشروع.
ويشكّل وكيل `/api` من المصدر نفسه في التطبيق جزءًا من هذا التصميم. لا تنشر
المنفذ 4311 على الإنترنت لمجرد تسهيل تكامل داخلي.

لا تعرض مسارات الموقع العام إلا المحتوى المنشور الموجّه للقرّاء والبحث
والبيانات الوصفية ومسارات العمل العامة صراحةً. ولا تمنح صلاحيات لوحة التحكم.
تظل بيانات اعتماد المشغّل وعامل المعالجة منفصلة عن وصول القرّاء ومساحة العمل.

تمثل نقطة MCP المصادَق عليها عبر HTTP عقد تكامل منفصلًا وصريحًا. وهي معطلة
افتراضيًا، وتقبل مفاتيح API مرتبطة بالمشروع وتحمل `mcp:connect` ونطاقات قراءة
دقيقة، ولا تحول مسارات لوحة التحكم غير الموثقة إلى API كتابة عامة مدعومة.
تغطي محولات القراءة محتوى وملخصات محدودة للبحث والاستخدام والاستحقاقات
والإضافات والسمات والتكاملات والتشغيل. تتحقق معاينة استيراد السمة من دون كتابة؛
ويبقى النشر وإعادة الفهرسة وتصدير الاستخدام وبيانات اعتماد المزوّد وعمليات
تغيير المجالات الجديدة غير متاحة. راجع [ربط عملاء MCP بأمان](/self-hosting/mcp).

## التكامل الآمن

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

لا يزال Nibleaf قبل الإصدار 1.0، لذلك لا تمثّل المسارات الداخلية غير الموثّقة
عقد توافق. اقترح احتياجات التكامل المستقر عبر بلاغ عام من دون تضمين تفاصيل
البيئة الخاصة.

## مراجع API المنشورة للعملاء

واجهة API لمنصة Nibleaf ومرجع API الخاص بمشروع توثيق هما منتجان مختلفان. لنشر
مرجع مشروع، افتح **الإعدادات ← مرجع API**، واختر تسمية التنقل ومساره، ثم استخدم
أحد المصادر المدعومة:

- ارفع أو الصق مستند JSON أو YAML واحدًا بحجم أقصاه 5 MB؛
- اجلب عنوان URL عامًا عبر HTTP(S) من دون بيانات اعتماد مضمّنة؛ أو
- اقرأ ملفًا ذا مسار نسبي إلى المستودع من مستودع GitHub أو GitLab عام ومتصل.

يتحقق Nibleaf من OpenAPI 3.x قبل الحفظ، ويحل ملفات `$ref` الخارجية العامة
ويجمعها داخل المستند المخزن. تعمل المراجع النسبية مع مصادر URL والمستودع، ويمكن
للمستند المرفوع أو الملصق استخدام روابط HTTP(S) عامة ومطلقة. يقتصر الحجم المجمع
على 5 م.ب. و20 ملفًا خارجيًا. وتكون كل عملية جلب محدودة بالوقت والحجم، وترفض
وجهات الشبكات الخاصة وبيانات الاعتماد وعمليات إعادة التوجيه غير الآمنة وإعادة
ربط DNS.

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

يستخدم المرجع المنشور Scalar. تنتقل طلبات التجربة مباشرة من متصفح القارئ إلى
واجهة API الموصوفة؛ لا يمرّر Nibleaf الطلبات عبر وكيل، ولا يحقن بيانات اعتماد،
ولا يحتفظ بالمصادقة، ولا يسجّل أسرار الطلبات. يجب أن تسمح واجهة API بمصدر
التوثيق المنشور ضمن سياسة CORS لديها. اختبر طلبًا واحدًا غير ضار ببيانات اعتماد
مؤقتة، وامسحها قبل مشاركة المتصفح أو تسجيل دليل مرئي.