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