בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- OWASP Foundation
- כותבים טכניים:
- sshniro
- שם הפרויקט:
- שיפורים במסמכי התיעוד של 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 מספק מסגרת משותפת למפתחים, לבודקים ול-DevOps ליצירה, לתחזוקה ולבדיקה של ממשקי API. ניתן להשתמש במפרטים המלאים של Open API עבור ZAP כדי ליצור באופן אוטומטי את קובצי ה-swagger. ניתן לשלב את קובצי Swagger בממשק המשתמש של אפליקציית האינטרנט של ZAP (אפליקציית שולחן עבודה) כדי לספק למשתמשים לקוח בדיקת API עשיר.
מלבד מסמכי התיעוד של ה-API, בכוונתי להשתמש בממיר swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) כדי ליצור את מסמכי ה-API בפורמט Markdown. הגישה הזו (swagger-converter) מפשטת את היצירה של תיעוד עדכני של ממשקי API מסוג RESTful, על ידי שילוב של תיעוד שנכתב ביד עם תיעוד API שנוצר באופן אוטומטי על ידי Swagger. התוצאות יהיו דומות למסמכי העזרה של ה-API של Github. (https://developer.github.com/v3/). במסמך הידני הזה יהיו מסמכים ברמה גבוהה שמסבירים איך להשתמש בממשקי ה-API כדי לבצע משימה מסוימת. לדוגמה, סריקת API של ספידר היא משימה ממושכת, והמשתמש צריך לדגום את ה-API באופן קבוע כדי לדעת מה סטטוס ה-API. לכן, במסמכים ברמה גבוהה אלה נסביר אילו ממשקי API ישמשו לביצוע פעולה, ונפנה למסמכי swagger שנוצרו באופן אוטומטי לקריאה נוספת.
הווטרסנט הוטמעו יותר מ-380 ממשקי API. בהתחלה אני מציע לתעד את כל ממשקי ה-API ולכלול תיאור של ממשקי ה-API, מידע לגבי פרמטרים, תגובות מוצלחות וכישלונות של ממשקי ה-API. כבר בוצעה בדיקת POC לדוגמה, ופרטים נוספים מופיעים בהצעה המקושרת.
תקופת הזמן של שלושת החודשים תחולק לשלושה שלבים. בשלב הראשון ייצרו את מפרטי ה-API הפתוח ל'סריקה פעילה', ממשקי API בסיסיים (150 ומעלה). במקביל ליצירת קובצי הסוואג, ייווצרו גם המסמכים הרלוונטיים של התרחיש לדוגמה/ מסמכים ברמה גבוהה על אופן השימוש בממשקי ה-API לביצוע משימות ספציפיות. אפשר לנהל גרסאות וליצור קבצים באופן אוטומטי כדי להסיר עבודות ידניות. כתוצאה מכך, קובצי Markdown יכולים להתארח כדפי אינטרנט או לייצא אותם כ-PDF.
בשלב השני תיכתב תיעוד של Spider, Autoupdate, Context, Status ו-Search APIs, וייווצרו מאמרים רלוונטיים בנושא תרחישים לדוגמה באמצעות קובצי Markdown.
בשלב האחרון נספק מידע על שאר ממשקי ה-API שלא מתועדים ועל תרחישים לדוגמה רלוונטיים. בחודש האחרון, אני מתכנן להתייחס גם לתרחישי שימוש שבהם צריך להפעיל כמה רכיבי API כדי לבצע משימה.