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