פעמים רבות אנו חושפים את הממשק שאנו כותבים ללקוחות או לקבוצות אחרות בפרויקט הרבה לפני ששכבות אחרות (לוגיקה למשל) כתובות ע”מ לאפשר פיתוח חופף. את התיעוד של הממשק כתבנו פעמים רבות כדף HTML סטטי או בעזרת כלים כמו postman. כלים אלו מתעדים את הממשק בעזרת HTTP ואינם תלויי שפת המימוש.
החסרון המשמעותי ביותר של שיטות אלו הוא הצורך לעדכן בכל פעם שהממשק משתנה (שינוי, הוספה, הורדה) ולכן חיפשנו דרך להפיכת התהליך לאוטומטי – בכל שינוי בממשק יתבצע עדכון אוטומטי של התיעוד.
השתמשנו בשרשרת של כלים ע”מ לממש זאת:
- jaxrs-analyzer איפשר לנו “לתרגם” את הממשק שלנו לקובץ swagger. השתמשנו ב Gradle (כחלק מתהליך הבילד הרגיל) ע”מ לבצע את הפעולה הזו.
- השלב הבא היה להשתמש ב swagger-ui ע”מ לחשוף את התיעוד כלפי חוץ.
כך, אחרי שהממשק מתעדכן, התיעוד שלו מתעדכן ונחשף החוצה באופן אוטומטי. נח למפתחים ונח ללקוחות של הממשק.