این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه ی پروژه
- سازمان متن باز:
- بنیاد OWASP
- نویسنده فنی:
- اسشنیرو
- نام پروژه:
- بهبود اسناد ZAP API
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
ZAP یک API بسیار قدرتمند دارد که به ما امکان می دهد تقریباً هر کاری را که ممکن است از طریق رابط دسکتاپ انجام دهیم. با این حال، برای استفاده مؤثر از APIها، به درک خوبی از رابط کاربری نیاز است. این به این دلیل است که بیشتر APIها به طور مستقیم با رابط کاربری پروکسی ZA مرتبط هستند. یک API مستند و سند استفاده/مورد استفاده می‌تواند به غلبه بر این تنگنا هنگام آزمایش APIها کمک کند.
در حال حاضر، اسناد API به صورت خودکار تولید می‌شوند، اطلاعات کمی در مورد پارامترهای درگیر ارائه می‌دهند، و فرصت کمتری را به جامعه می‌دهد تا در اسناد API مشارکت کند. علاوه بر این، UI مبتنی بر وب (نسخه دسکتاپ) که در داخل ZAP استفاده می‌شود نیز از فهرست API تولید شده خودکار برای فراخوانی استفاده می‌کند. این واسط فراخوانی API مبتنی بر وب همچنین اطلاعات بسیار محدودی در مورد نحوه استفاده از API و آنچه در هنگام فراخوانی APIها انتظار می رود (به عنوان مثال نتایج API) ارائه می دهد. بنابراین در این پیشنهاد، من رویکرد جدیدی را برای مستندسازی APIها پیشنهاد می کنم.
ایده این است که اسناد API را با مشخصات Open API 3 دوباره ایجاد کنیم. Open API یک چارچوب مشترک برای توسعه دهندگان، آزمایش کنندگان و توسعه دهندگان برای ساخت، نگهداری و آزمایش API ها فراهم می کند. مشخصات تکمیل شده Open API برای ZAP را می توان برای تولید خودکار فایل های swagger استفاده کرد. فایل‌های Swagger را می‌توان در رابط کاربری وب ZAP (برنامه دسکتاپ) ادغام کرد تا یک کلاینت آزمایشی API غنی را برای کاربران فراهم کند.
جدا از اسناد API، من قصد دارم از مبدل swaggerToMarkdown ( https://github.com/Swagger2Markup/swagger2markup ) برای تولید اسناد API در قالب Markdown استفاده کنم. این رویکرد (تبدیل کننده swagger) تولید اسناد به روز RESTful API را با ترکیب اسنادی که به صورت دستی نوشته شده اند با اسناد API تولید شده توسط Swagger ساده می کند. نتایج مشابه اسناد API Github خواهد بود. ( https://developer.github.com/v3/ ). این سند دست‌نویس دارای اسناد سطح بالایی است که توضیح می‌دهند چگونه APIها باید برای انجام یک کار خاص استفاده شوند. به عنوان مثال، اسکن Spider API یک کار طولانی مدت است و کاربر باید به طور مداوم از API نظرسنجی کند تا از وضعیت API مطلع شود. از این رو، این اسناد سطح بالا در مورد اینکه کدام API برای انجام یک عمل استفاده می شود و برای مطالعه بیشتر به اسناد swagger خود تولید شده اشاره خواهد کرد.
تعداد کل بیش از 380 API در پروکسی ZA پیاده سازی شده است. من در ابتدا پیشنهاد می‌کنم که همه APIها با توضیحاتی در مورد APIها، اطلاعات مربوط به پارامترها، پاسخ‌های موفقیت و شکست APIها مستند شوند. قبلاً یک POC نمونه انجام شده است و جزئیات اضافی را می توان در پروپوزال مرتبط مشاهده کرد.
دوره سه ماهه به سه مرحله تقسیم می شود. مرحله اول، مشخصات Open API را برای Active Scan، Core API (150+) ایجاد می کند. به موازات ایجاد فایل‌های swagger، مستندات مورد استفاده/ اسناد سطح بالا در مورد نحوه استفاده از APIها برای انجام وظایف خاص نیز ایجاد خواهد شد. این می‌تواند برای حذف کارهای دستی نسخه‌بندی و تولید شود و فایل‌های علامت‌گذاری شده به‌عنوان صفحات وب میزبانی شوند یا به‌صورت PDF صادر شوند.
مرحله دوم شامل مستندسازی Spider، Auto Update، Context، Status، Search API و ایجاد مقالات مورد استفاده مربوطه از طریق فایل‌های Markdown است.
مرحله نهایی بقیه APIهای غیرمستند و موارد استفاده مرتبط آنها را پوشش خواهد داد. در ماه گذشته، من قصد دارم موارد استفاده ای را نیز پوشش دهم که برای انجام یک کار نیاز به فراخوانی چندین مؤلفه API دارند.