איך לתעד RESTfull
-
לצורך העניין מדובר אפליקציית nodeJS שאמורה לעקוב אחרי אתרי אינטרנט באמצעות RSS ולשלוח עדכונים למייל. האפליקציה בנויה בצורה של RESTfull api, וממשק שמתקשר איתו עם ajax (jQuery וכדו').
חילקתי את הAPI לכמה נתיבים מרכזיים, לדוגמה
/api/usersלכל הפעולות שקשורות למשתמשים - הרשמה, אימות דוא"ל, התחברות וכו', נתיב נוסף להוספת/קבלת פריטים, ונתיב נוסף לניהול ההרשמות - הרשמה, ביטול הרשמה וכו'.
לכל API יש כמובן את המפרט שלו - מה הוא מצפה לקבל - איזה פרמטרים בurl, איזה body, וכמובן מתודת HTTP - GET/POST/DELETE וכו'. וכן מה הוא מחזיר בתגובה במקרה הצלחה ובמקרה שגיאה - קוד סטטוס HTTP - 200, 429, 400 וכו', body, יצירת/מחיקת קוקיס, וכו'.השאלה איך אני מתעד את זה בצורה מפורטת וברורה (לבן אנוש, לא איזה "מפרט XML/JSON או "תרשים זרימה" שצריך תואר שני כדי לפענח אותו), כך שאם ארצה לדוגמה עוד כמה חודשים להוסיף/להוריד/לתקן משהו בקוד, לא אצטרך לחפור ולבדוק במידלוור של ההתחברות מה הוא מצפה לקבל, ואז לבדוק במידלוורס של האימותים (של הbody/parms) וכו' (שנעשו עם ajv איזה פרמטרים הפונקציה מצפה לקבל, וכן הלאה, ושלא לומר שבשביל להבין מה הנתיב אמור להחזיר אני יצטרך ממש לחפור בקוד עצמו, אלא יהיה לי תיעוד מסודר וברור מה ואיך אמורים לשלוח, ומה מקבלים בחזרה,
האם יש איזה פתרון קל - איזהשהו "מחולל" לייצר את התיעוד הנ"ל בצורה גרפית קלה ופשוטה?
וגם באם לא - באיזה צורה נכון לכתוב את זה, גם ידנית?
תודה מראש -
@צדיק-תמים בטח ראית, אבל אם לא:
https://swagger.io
חברה זו מנסה לטפל בבעיה שלך -
Swagger זה מימוש של התקן המתקרא OpenAPI (גירסה מס' 3), התקן מיועד עבור תיעוד REST APIs.
Swagger גם מספקת כלים אוטומטיים ליצור את התיעוד וכלים חזותיים (Middlewares) לצפות בתיעוד (התקן כולל קובץ JSON\YAML בלבד) בנוסף לאפשרות לבצע קריאה לכל אחד מהEndpoint החשופים בתיעוד, עם הפרמטרים וההדרים הדרושים.
