مولّد وثائق واجهة برمجة التطبيقات mewayz

منشئ مستندات API في Mewayz

توفر الوظيفة الإضافية API Docs Generator مرجعًا داخل التطبيق وقابل للتصفح لـ Mewayz REST API.

Mewayz- الوحدة الأصلية — لا Mewayz المنبع. التوثيق مؤلف من مصدر الحزمة في packages/mewayz/ApiDocsGenerator/.

رابط العرض التجريبي

مقدمة

توفر الوظيفة الإضافية API Docs Generator للمشغلين ومطوري الطرف الثالث مرجعًا من صفحة واحدة يمكن البحث فيه عن Mewayz REST API. إنه المعادل داخل التطبيق لواجهة مستخدم Swagger - يتم عرض كل نقطة نهاية موثقة ومخطط الطلب ومخطط الاستجابة ومثال الحمولة داخل المسؤول بحيث لا يضطر المطور أبدًا إلى مغادرة النظام الأساسي للتكامل.

سطح الوثائق هو مدفوع بالمخطط: تحمّل الحزمة ملفات JSON مُسبقة البناء من src/documentation/ (واحد لكل نطاق: items.json وproject.json وaccount.json وغيرها)، مُفهرَسة بمفتاح رئيسي config.json تُدرج النطاقات المراد عرضها وأسماء عرضها. هذا يعني أن المستندات دقيقة وفقًا للعقد الفعلي — فهي لا تنحرف عن المسارات لأن كل إصدار يشحن المسارات ومخطط JSON المطابق معًا.

كيفية تمكين هذه الوحدة

لإعداد إضافة مولّد وثائق API، يمكنك اتباع هذا الرابط: إضافة الإعداد.

الإضافة مقيّدة بـ PlanModuleCheck:ApiDocsGenerator. فعّلها على خطة أو لكل مستأجر عبر الإضافات صفحة المسؤول؛ بمجرد التفعيل، يظهر إدخال «مستندات API» في الشريط الجانبي.

كيفية الوصول إلى وثائق API

• قم بتسجيل الدخول إلى Mewayz وانتقل إلى وثائق API في الشريط الجانبي.
• يُحمّل المرجع المؤلّف من صفحة واحدة على /api-docs. المسار هو auth-

مُقيَّد (web + auth + verified + PlanModuleCheck)، لذا يُعاد توجيه الزوار المجهولين إلى صفحة تسجيل الدخول.

• المرجع مجمّع حسب المجال. يسرد كل مجال كل

نقطة النهاية المتاحة مع فعل HTTP والمسار والترويسات المطلوبة ومخطط نص الطلب ومثال على الاستجابة.

المصادقة على Mewayz API

جميع نقاط نهاية Mewayz API الموثقة هنا محمية بواسطة **Laravel Sanctum** وتتطلب رمزًا مميزًا لحاملها في Authorization الترويسة. يُفرض نوع المحتوى عبر api.json البرمجية الوسيطة — يجب أن يتضمن كل طلب Content-Type: application/vnd.api+json (أو رأس JSON المكافئ) وإلا يتم رفض الطلب قبل وصوله إلى المتحكم.

لإصدار رمز:

• من قائمة ملف المشغّل الشخصي، افتح رموز واجهة برمجة التطبيقات.
• انقر إنشاء رمز، سمِّه، وانسخ السر فوراً

(يُعرض السر مرة واحدة فقط).

• مرّر الرمز في كل استدعاء لواجهة API: Authorization: Bearer <token>.

تغطية نقاط النهاية

تغطي مخططات JSON المجمّعة المجالات التالية:

• إدارة المستخدمين — /api/users، /api/user/store|update|delete|reset-password|verify
• المنتجات والخدمات — /api/products، /api/product/create|update|detail|delete، بالإضافة إلى الفئات والضرائب والوحدات ومخزونات المستودعات
• إدارة المشاريع — /api/projects، /api/project/{id}/task-board، المعالم، تتبّع الأخطاء
• فوترة المبيعات والمشتريات — /api/sales-invoice، /api/sales-invoice-return، /api/purchase-invoice، /api/purchase-return
• تحويلات المستودعات والمخزون — /api/warehouse، /api/warehouse/product/{warehouse_id}، /api/transfer
• عروض المبيعات — /api/sales-proposal
• إدارة الموارد البشرية — /api/employees، /api/attendance، /api/leave-application، /api/payrolls
• إدارة علاقات العملاء والعملاء المحتملون — /api/leads، /api/deal/*، /api/pipeline، /api/lead-stage، /api/labels، /api/sources
• المحاسبة — /api/chart-of-accounts، /api/customers، /api/vendors، /api/bank-accounts، /api/revenues، /api/expenses
• نقطة البيع — /api/pos

الأذونات

تخضع رؤية إدخال مستندات واجهة برمجة التطبيقات في الشريط الجانبي لإذن Spatie manage-api-docs. لا يرى المشغّلون الذين لا يملكون هذا الإذن إدخال القائمة ويتلقّون خطأ 403 إذا زاروا /api-docs مباشرةً.

ملاحظات المشغّل

• الوثائق للقراءة فقط اليوم — لا يوجد «جرّبه»

زر لتنفيذ الاستدعاءات مباشرة من صفحة المستندات. (استخدم أداة مثل Postman أو curl للاختبار مقابل نقاط النهاية الموثّقة.)

• تعيش مخططات JSON ضمن نظام التحكم في المصدر في

packages/mewayz/ApiDocsGenerator/src/documentation/. عند شحن نقاط نهاية API جديدة، يُضاف أو يُوسّع ملف JSON المطابق في الإصدار نفسه.

• يرى المستأجرون بعلامة بيضاء واجهة المستندات تلقائيًا مُقيّدة بنطاق

اسم علامتهم التجارية الخاصة وعنوان URL الأساسي؛ لا حاجة للحفاظ على وثائق منفصلة لكل مستأجر.