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

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

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

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

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

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

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

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

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

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

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

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

لا يزال 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 لديها. اختبر طلبًا واحدًا غير ضار ببيانات اعتماد مؤقتة، وامسحها قبل مشاركة المتصفح أو تسجيل دليل مرئي.