تحتوي هذه الصفحة على تفاصيل مشروع كتابة فني مقبول ضمن "موسم المستندات" من Google.
ملخص المشروع
- مؤسسة البرامج المفتوحة المصدر:
- مؤسسة OWASP
- الكاتب الفني:
- شنيرو
- اسم المشروع:
- تحسين وثائق ZAP API
- طول المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
لدى ZAP واجهة برمجة تطبيقات قوية للغاية وتتيح لنا تنفيذ كل ما هو ممكن تقريبًا عبر واجهة سطح المكتب. ومع ذلك، لاستخدام واجهات برمجة التطبيقات بشكل فعّال، لا بد من فهم جيد لواجهة المستخدم. ويرجع ذلك إلى أنّ معظم واجهات برمجة التطبيقات ترتبط مباشرةً بواجهة المستخدم للخادم الوكيل ZA. واجهة برمجة التطبيقات الموثَّقة جيدًا ومستند حالة الاستخدام/ الاستخدام يمكن أن تساعد في التغلب على هذا المعوق عند تجربة واجهات برمجة التطبيقات.
في الوقت الحالي، يتم إنشاء مستندات واجهة برمجة التطبيقات تلقائيًا، وتوفر القليل من المعلومات حول المعلمات المعنية، كما أنها تتيح فرصة أقل للمجتمع للمساهمة في مستندات واجهة برمجة التطبيقات. بالإضافة إلى ذلك، إنّ واجهة المستخدم المستندة إلى الويب (إصدار سطح المكتب) المستخدَمة داخل ZAP تستخدم أيضًا قائمة واجهة برمجة التطبيقات التي تم إنشاؤها تلقائيًا من أجل الاستدعاء. كما توفر واجهة المستخدم لاستدعاء واجهة برمجة التطبيقات المستندة إلى الويب معلومات محدودة للغاية حول كيفية استخدام هذه الواجهة وما يمكن توقعه عند استدعاء واجهات برمجة التطبيقات ( على سبيل المثال، نتائج واجهة برمجة التطبيقات). لذلك، نقترح في هذا الاقتراح منهجًا جديدًا لتوثيق واجهات برمجة التطبيقات.
والفكرة هي إعادة إنشاء مستندات واجهة برمجة التطبيقات باستخدام مواصفات Open API 3. توفر واجهة برمجة التطبيقات المفتوحة إطارًا مشتركًا للمطورين والمختبِرين ومطوري البرامج لإنشاء واجهات برمجة التطبيقات وصيانتها واختبارها. يمكن استخدام مواصفات Open API المكتملة لـ ZAP لإنشاء ملفات التباهي تلقائيًا. يمكن دمج ملفات Swagger في واجهة مستخدم تطبيق الويب الخاص بـ ZAP (تطبيق سطح المكتب) لتوفير برنامج اختبار غني لواجهة برمجة التطبيقات للمستخدمين.
بصرف النظر عن وثائق واجهة برمجة التطبيقات، أخطّط لاستخدام المحوِّل swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) لإنشاء مستندات واجهة برمجة التطبيقات بتنسيق Markdown. ومن خلال هذا المنهج (تحويل التباهي)، يمكنك إنشاء مستندات حديثة حول واجهة برمجة التطبيقات RESTful من خلال الجمع بين المستندات المكتوبة بخط اليد ووثائق واجهة برمجة التطبيقات التي تم إنشاؤها تلقائيًا من خلال منصة Swagger. ستكون النتائج مماثلة لوثائق واجهة برمجة التطبيقات الخاصة بـ جيت هب. (https://developer.github.com/v3/). سيحتوي هذا المستند المكتوب بخط اليد على مستندات عالية المستوى تشرح كيفية استخدام واجهات برمجة التطبيقات من أجل أداء مهمة معينة. على سبيل المثال، يُعدّ فحص واجهة برمجة تطبيقات Spider مهمة طويلة الأمد وعلى المستخدم استطلاع رأي واجهة برمجة التطبيقات باستمرار لمعرفة حالة واجهة برمجة التطبيقات. وبالتالي، ستناقش هذه المستندات عالية المستوى واجهات برمجة التطبيقات التي سيتم استخدامها لتنفيذ إجراء، كما ستشير إلى مستندات التباهي التي تم إنشاؤها تلقائيًا لمزيد من القراءة.
وقد تم تنفيذ إجمالي أكثر من 380 واجهة برمجة تطبيقات في الخادم الوكيل ZA. أقترح في البداية توثيق جميع واجهات برمجة التطبيقات مع وصف لهذه الواجهات، ومعلومات عن المعلَمات، ونجاحها، واستجابات الإخفاق في واجهات برمجة التطبيقات. سبق أن تم إنشاء نموذج لجهة التواصل، ويمكن الاطّلاع على تفاصيل إضافية في الاقتراح المرتبط.
سيتم تقسيم فترة الأشهر الثلاثة إلى ثلاث مراحل. ستنشئ المرحلة الأولى مواصفات Open API للفحص النشط وواجهات برمجة التطبيقات الأساسية (150+). وبالتوازي مع إنشاء ملفات التباهي، سيتم أيضًا إنشاء وثائق حالة الاستخدام ذات الصلة/ المستندات عالية المستوى حول كيفية استخدام واجهات برمجة التطبيقات لتنفيذ مهام محدّدة. ويمكن إنشاء نسخة من هذا المحتوى وإنشائها تلقائيًا لإزالة العمل اليدوي ويمكن استضافة ملفات Markdown الناتجة كصفحات ويب أو تصديرها كملف PDF.
ستتناول المرحلة الثانية توثيق برامج العنكبوت والتحديث التلقائي والسياق والحالة وواجهات برمجة تطبيقات البحث وإنشاء مقالات حالة الاستخدام ذات الصلة عبر ملفات Markdown.
ستتناول المرحلة الأخيرة بقية واجهات برمجة التطبيقات غير الموثقة وحالات استخدامها ذات الصلة. في الشهر الماضي، أنوي أن أتناول أيضًا حالات الاستخدام التي تتطلب استدعاء مكوّنات متعددة من واجهة برمجة التطبيقات لتنفيذ مهمّة.