דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- קרן OWASP
- כתב טכני:
- שנירו
- שם הפרויקט:
- שיפור התיעוד של ZAP API
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
ל-ZAP יש ממשק API חזק במיוחד שמאפשר לנו לעשות כמעט כל מה שאפשר דרך הממשק של המחשב השולחני. עם זאת, כדי להשתמש בממשקי ה-API ביעילות, נדרשת הבנה טובה של ממשק המשתמש. הסיבה לכך היא שרוב ממשקי ה-API קשורים ישירות לממשק המשתמש של שרת ה-proxy של ZA. API ומסמך תרחיש לדוגמה של שימוש או שימוש מתועדים היטב יכולים לעזור לכם להתגבר על צוואר הבקבוק הזה במהלך השימוש בממשקי ה-API.
בשלב זה, מסמכי ה-API נוצרים באופן אוטומטי, מספקים מעט מידע לגבי הפרמטרים שמעורבים בהם, ומאפשרים לקהילה פחות הזדמנות לתרום לתיעוד ה-API. בנוסף, ממשק המשתמש מבוסס-האינטרנט (גרסה למחשב) המשמש בתוך ה-ZAP משתמש גם ברשימת ממשקי ה-API שנוצרה באופן אוטומטי לצורך הפעלה. ממשק המשתמש מבוסס-האינטרנט להפעלת ה-API מספק גם מידע מוגבל מאוד לגבי אופן השימוש ב-API ולמה אפשר לצפות כשמפעילים את ממשקי ה-API ( למשל, תוצאות של API). לכן, בהצעה זו, אני מציע גישה חדשה לתיעוד ממשק ה-API.
הרעיון הוא ליצור מחדש את מסמכי ה-API בהתאם למפרטים של Open API 3. Open API מספק מסגרת משותפת למפתחים, לבודקים ולמפתחים ליצירה, לתחזוקה ולבדיקה של ממשקי API. כדי ליצור באופן אוטומטי קובצי סוואג, אפשר להשתמש במפרטים המלאים של ה-Open API עבור ZAP. ניתן לשלב את קובצי Swagger בממשק המשתמש של אפליקציית האינטרנט (Desktop App) של ZAP כדי לספק למשתמשים לקוח עשיר לבדיקת ממשק ה-API.
מלבד מסמכי ה-API, בכוונתי להשתמש בממיר 'swaggerToMarkdown' (https://github.com/Swagger2Markup/swagger2markup) כדי ליצור את מסמכי ה-API בפורמט Markdown. הגישה הזו (ממיר סוואג) מפשטת את היצירה של מסמכי RESTful API עדכניים על ידי שילוב בין תיעוד שנכתב באופן ידני לבין תיעוד API שנוצר באופן אוטומטי על ידי Swagger. התוצאות יהיו דומות לתיעוד ה-API של GitHub. (https://developer.github.com/v3/). המסמך הזה כתוב בכתב יד ויכלול מסמכים ברמה גבוהה שמסבירים איך יש להשתמש בממשקי ה-API כדי לבצע משימה מסוימת. לדוגמה, סריקה של Spider API היא משימה ממושכת, והמשתמש צריך לבצע דגימה של ה-API באופן קבוע כדי לדעת את הסטטוס של ה-API. לכן, המסמכים האלה ברמה העליונה ידונו באילו ממשקי API שישמשו לביצוע פעולה ויפנו אל מסמכי 'סוואג' שנוצרו באופן אוטומטי להמשך קריאה.
בשרת proxy של ZA הוטמע מספר כולל של יותר מ-380 ממשקי API. ההצעה שלי היא לתעד את כל ממשקי ה-API עם תיאור לממשקי ה-API, מידע לגבי הפרמטרים, התשובות הצלחה והכשל של ממשקי ה-API. יש כבר איש קשר לדוגמה לדוגמה, ואפשר לראות פרטים נוספים בהצעה המקושרת.
התקופה של שלושת החודשים תחולק לשלושה שלבים. בשלב הראשון ייווצר מפרטים של Open API עבור Active Scan, ממשקי Core API (150+). במקביל ליצירת הקבצים המוכרים, ייווצרו גם המסמכים הרלוונטיים לתרחיש לדוגמה/ מסמכים ברמה גבוהה, שבהם מוסבר איך להשתמש בממשקי ה-API כדי לבצע משימות ספציפיות. אפשר לערוך גרסאות כאלה וליצור אותן באופן אוטומטי כדי להסיר עבודות ידניות. בנוסף, אפשר לארח קובצי Markdown בתור דפי אינטרנט או לייצא אותם כ-PDF.
השלב השני יכלול תיעוד של 'ספיידר', 'עדכון אוטומטי', 'הקשר', 'סטטוס', ממשקי API של חיפוש ויצירת מאמרים רלוונטיים לתרחיש לדוגמה באמצעות קובצי Markdown.
השלב האחרון יעסוק בשאר ממשקי ה-API הלא מתועדים ותרחישי השימוש הרלוונטיים בהם. בחודש האחרון, אני מתכנן לכלול גם תרחישים לדוגמה שמחייבים להפעיל מספר רכיבי API כדי לבצע משימה מסוימת.