Swagger - מה זה ועל מה זה?
-
כן
תיעוד זה הדבר החם הבא, סטאק אובפלוו פתחו במסע לכבוש את השוק, ואני מניח שיש עוד הרבה שחקנים שלא שמענו עליהם.
למעשה מייקרוסופט יש להם מערכת תיעוד אוטומטי מתוך הקוד, (אם אתה עובד לפי כללי האקסמל שלהם מעל כל פונקציה וכו) וגם ג'אווה. אלא שמכיוון שהעולם עובר ל API הרי שהתיעוד צריך להיות ציבורי וכו'.פורסם במקור בפורום CODE613 ב23/09/2016 15:20 (+03:00)
-
לפי מה שהבנתי זה פשוט רכיב תוכנה בצד השרת שחושף את כל הפעולות בהם הוא תומך.
היה את זה פעם בWebService: צד השרת נותן רשימה של הפעולות האפשריות פרמטרים וכו'.
זה הרבה יותר מדוקמנטציה, זה יכול לשרת מחוללי קוד ולפשט מאוד את החיים. למשל אם אתה כותב תוכנה שממשקת עם גוגל מפות. אז אתה עובד עם RestApi שכל פעם אתה צריך לכתוב שאילתות http + בדיקה איזה פרמטרים אתה צריך וכו'.
בWebService הישן יכולת ע"י כלי לחולל מעטפת לAPI - הוא יוצר פונקציה לכל פעולה אפשרית בסרויס, ואתה צריך רק לכתוב את הפונקציה והפרמטרים. זה גם חיסכון קוד ובIDE עם השלמה אוטומטית זה גם מוסיף נוחות עצומה.
בתקן RestApi לא כלול שום יכולת לתיעוד עצמי (Discoverablity - יכולת לחשיפה עצמית). אם אתה לא יודע מה הפרמטרים, אין לך מה לעשות. ממילא גם א"א לבנות מחוללי קוד וכו'.
הSwagger הזה נותן יכולת למפתח השירות, להוסיף דף תיעוד האפרויות - דינמית. יש להם גם כלים לחולל קוד לקוח לשירות בו יש את הרכיב שלהם.
ככה הבנתי.
מצאתי מאמר שמתאר עבודה עם זה:
http://www.codeproject.com/Articles/1078249/RESTful-Web-API-Help-Documentation-using-Swagger-Uפורסם במקור בפורום CODE613 ב28/09/2016 14:06 (+03:00)
-
גוגל למשל כתבו כלי לשוטט בAPI שלהם:
https://developers.google.com/apis-explorer/#p/.
קשה להרים כזה כלי ויש צורך לכתוב את השירותים בצורה שעוזרת לכלי הזה לגלות אותם או לעדכן מסד ידני. הswagger עושה זאת לבד ואף טוב יותר- כי זה מנסה להיות תקני ולהיות מוכר ע"י צדדים שלישיים.
רק מה? שגיליתי שיש אלף שכמותם בחיפוש גוגל של המילים rest api discoverability. אני מרגיש שחסר לי עוד משהו בלהבין את ייחודיותם.פורסם במקור בפורום CODE613 ב28/09/2016 14:10 (+03:00)
-
מי שרוצה דוגמא חיה.
יש את החבילה הזאת.
https://www.npmjs.com/package/ari-clientזה API למרכזיה של אסטריסק. וזה משתמש בחבילה הזו.
https://www.npmjs.com/package/swagger-clientפורסם במקור בפורום CODE613 ב28/09/2016 15:12 (+03:00)
