هذا دليل للمساهمة في توثيق واجهة برمجة التطبيقات (API) الرسمية لـ Discourse.
مستوى المستخدم المطلوب: مطور
مطلوب الوصول إلى وحدة التحكم (Console)
هل ترغب في المساهمة في توثيق واجهة برمجة التطبيقات الرسمية على https://docs.discourse.org؟ سيشرح لك هذا الدليل كيفية القيام بذلك خطوة بخطوة.
ملخص
سيرشدك هذا التوثيق خلال الخطوات التالية:
- إعداد المتطلبات الأساسية.
- استنساخ مستودع توثيق واجهة برمجة التطبيقات لـ Discourse.
- تعديل ملفات التوثيق الخاصة بواجهة برمجة التطبيقات.
- عرض التغييرات محليًا.
- إنشاء طلب سحب (Pull Request).
المتطلبات الأساسية
يجب أن يكون لديك تثبيت لتطوير Discourse. إذا لم يكن لديك واحد، فاتبع الدليل المناسب لبيئتك في هذه المواضيع.
استنساخ مستودع توثيق واجهة برمجة التطبيقات لـ Discourse
بافتراض أن تثبيت تطوير Discourse الخاص بك موجود داخل مجلد المنزل ~/، تابع الخطوات التالية لاستنساخ المستودع:
-
من مجلد المنزل الخاص بك، استنسخ المستودع من https://github.com/discourse/discourse_api_docs:
git clone https://github.com/discourse/discourse_api_docs -
يجب أن يكون لديك الآن مجلدا
discourseوdiscourse_api_docsجنبًا إلى جنب:~/discourse/ ~/discourse_api_docs/
تعديل ملفات توثيق واجهة برمجة التطبيقات
يجب عليك تعديل التوثيق مباشرة من ~/discourse/spec/requests/api/.
- راجع المجلد على GitHub: discourse/spec/requests/api at main · discourse/discourse · GitHub
يمكن أيضًا المساهمة في توثيق واجهة برمجة التطبيقات للإضافات (Plugins) عبر ملفات المواصفات (spec files) الموجودة في plugins/*/spec/requests/api/.
بعد تعديل ملفات التوثيق، قم بتشغيل الأمر التالي من ~/discourse/:
bin/rake rswag:specs:swaggerize && cp openapi/openapi.yaml ~/discourse_api_docs/openapi.yml
سيتم إنشاء التوثيق باستخدام rswag ونسخه إلى ~/discourse_api_docs/.
ثم، قم بتحويل ملف YAML إلى JSON من ~/discourse_api_docs/:
npm install
node tojson.js
عرض التغييرات محليًا
لعرض التوثيق المحدّث الخاص بك، اتبع الخطوات التالية:
-
من
~/discourse_api_docs/، قم بتشغيل:npm install node server.js -
تصفح إلى http://localhost:3001 لرؤية التوثيق المحدث.
إنشاء طلب سحب (Pull Request)
بمجرد التأكد من أن كل شيء يبدو جيدًا، قم بإنشاء طلب سحب من مستودع discourse/discourse (ليس مستودع توثيق واجهة برمجة التطبيقات لـ Discourse).
يتم تحديث مستودع discourse_api_docs تلقائيًا يوميًا عبر سير عمل GitHub Actions يعيد إنشاء مواصفات OpenAPI من أحدث مواصفات نواة Discourse. لا تحتاج إلى تقديم طلب سحب (PR) منفصل إلى ذلك المستودع.
مشكلات شائعة وحلولها
الإبلاغ عن الأخطاء في توثيق واجهة برمجة التطبيقات لـ Discourse
إذا واجهت مشاكل أو أخطاء في توثيق واجهة برمجة التطبيقات لـ Discourse، يرجى الإبلاغ عنها في منتدى Discourse Meta - يمكنك اتباع دليل الإبلاغ عن الأخطاء لمساعدتك في القيام بذلك بفعالية.
ما هي المشكلة؟