הדף הזה מכיל את הפרטים של פרויקט כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- OpenMRS
- כותבים טכניים:
- Saurabh
- שם הפרויקט:
- הרחבת מסמכי התיעוד של GitHub למשתמשים בנושא API ל-REST
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
היעד העיקרי
שיפור מסמכי התיעוד של OpenMRS ל-API ל-REST שמבוסס על Swagger, כדי להוסיף הנחיות לשימוש ב-API.
תיאור הפרויקט
ה-API ל-REST של OpenMRS הוא אחד המנגנונים העיקריים שמאפשרים למפתחים לגשת לנתונים מ-OpenMRS. כבר יש תיעוד שנוצר באופן אוטומטי על סמך Swagger של OpenMRS Webservices API, וגם תיעוד סטטי שמבוסס על GitHub. אנחנו אמורים להרחיב את התיעוד הזה שמבוסס על GitHub במהלך Season of Docs.
סקירה כללית קצרה
אחרי קצת מחקר ב-OpenMRS Talk כפי שבורק הציע, הבנתי שהפרויקט הזה התחיל בשנת 2017 כפרויקט GSOC. המטרה העיקרית של גיאן ווראקוטי הייתה לשפר את התיעוד הקיים של ה-API ל-REST של OpenMRS, על ידי שיפור מפרט Swagger שלו ובאמצעות שיפורים באופן שבו מופק מפרט ה-Swagger כדי ליצור גרסה טובה יותר של מסמכי התיעוד של הסוואג. כל הפרטים הרלוונטיים שהושגו בפרויקט סיכמתי כאן בפוסט הזה ב-OpenMRS Talk, והם היו מועילים מאוד.
לאחר מכן, ב-2019, חדשנו את הפרויקט, ועברנו מתיקונים לתיעוד של Swagger שמייצרים גרסאות שונות בנושא. במקום זאת, פיתחנו מסמכי תיעוד סטטיים שמותאמים ל-GitHub, ואנחנו מתכוונים להרחיב אותם במהלך העונה הזו של Docs.
לפניכם תקציר של ההצעה לפרויקט הנוכחי שבכוונתי לתאר :
- מציאת דוגמאות בכמה שפות פופולריות (יש להן אזכור ספציפי של Java ו-JavaScript).
- הוספת תמיכה ב-Playground למסמכי התיעוד בלוח בקרת המשחקים, בדיוק כמו התכונה 'התנסות' .
- ארגון מחדש ושיפור העבודה שהתבצעה עד עכשיו.
- לחפש ולהוסיף את המשאבים החסרים.
- הוספת תיאור נוסף לקטע של המסוף במסמכים
תיאור מפורט
- צרו דוגמאות בשפות שונות.
מומלץ להוסיף דוגמאות ב-Java שיהיה מבוסס על SDK, ואז להוסיף דוגמאות ל-Retrofit. לדעתי, הוספת דוגמאות ל-Retrofit תוסיף עומק לתיעוד שלנו, כי הוספת דוגמאות בשפה נוספת כמו JavaScript לא תעזור באותה מידה. השתמשתי בממשקי ה-API ל-REST האלה בזמן העבודה על OpenMRS Android Client, ולא היו מקורות מידע שאפשר היה להיעזר בהם כשהזדקקתי לעזרה בשימוש בנקודות הקצה (endpoints) במיוחד ל-Android. ויכול להיות שאציג כאן כמה דוגמאות איכותיות, בהתאם לניסיון שלי בעבודה עם נקודות קצה של OpenMRS API בלקוח Android. אדבר על זה עם המנטורים שלי ואעבוד לפי מה שיוחלט. בנוסף, בנוסף להוספת דוגמאות לפעולות הנתמכות, כדאי להוסיף דוגמאות לאימות עם שרתי OpenMRS גם בשפות תכנות מסוימות. נכון לעכשיו, יש לנו רק דוגמאות ל-curl לצורך כך.
- הוספת תמיכה של Playground לבדיקת דוגמאות לממשקי API
השתמשתי בתכונה הזו במסמכי העזרה של swagger של OpenMRS שמתארח בשרת הדגמה, וזה כלי נוח מאוד שאפשר לכלול בכל מסמכי העזרה של API. בדקתי קצת כאן, ולא קשה להטמיע את המפרט של Swagger-UI במסמכי העזרה הסטטיים הנוכחיים. באמצעות מתגים להצגה והסתרה ושימוש בקוד הנוכחי של מסמכי התיעוד של Swagger. כך נוכל אפילו להבטיח שתכונת ההתנסות תישאר פעילה בהתאם למפרט הנוכחי של ה-API, זו אחת הדרכים שבהן נוכל לשלב תכונות של מגרש המשחקים בתיעוד הסטטי הנוכחי שלנו.
- ארגון מחדש ושיפור העבודה שהתבצעה עד עכשיו
בדיקת הדוגמאות הנוכחיות ל-curl
הקטע הזה הוא אחד מהדגשים העיקריים של הפרויקט השנה. נכון לעכשיו, במסמכי התיעוד של GitHub API יש רק דוגמאות ל-curl, וחלק מהן לא ניתן להריץ ישירות בשרת הדמו כדי לבדוק אותן ישירות מהדפדפן. אני אבדוק את כל נקודות הקצה הנוכחיות ואשמור מסמך פשוט עם דוגמאות שונות ל-curl שנקבל על הרצת בקשות ה-curl האלה. במקרה הצורך, אשתמש ב-Postman בנוסף לתכונת ההתנסות המובנית במסמכי התיעוד של הסמלים הקבילים.
חסרות תגובות API בחלק מהדוגמאות
נוספו תגובות לדוגמאות הקיימות של curl, אבל לחלק מהדוגמאות של curl אין תגובות. לדעתי, גם אם התשובות לא מפורטות, כמו בדרך כלל בפעולות כמו ניקוי משאבים, כדאי לכלול דוגמה לתשובה של API בפורמט JSON. עם זאת, תיעדנו את כל קודי התשובות האפשריים ואת הסיבה לקבלתם. לדעתי, כך הדוגמאות בתיעוד ה-API יהיו אחידות יותר.
חסרות דוגמאות שפועלות לפעולות שונות
לדעתי זה יהיה החלק החשוב ביותר בשיפור הקוד של העבודה שהושלמה בעבר במסמכי העזרה של ה-API. במסמכים יש דוגמאות קונקרטיות שאפשר להריץ ישירות באמצעות cURL, אבל חלק מהן קצת מופשטות, ומספקות מידע שימושי למפתחים מנוסים, אבל משאירות את המתחילים במצב של בלבול. כפי שהצלחתי להבין מהפוסט הזה ב-OpenMRS, שיחות טובות הן יקרות ערך, ולכן חוץ מהוספת דוגמאות של עבודה, יכולנו לתמוך בהדגשת תחביר, שלא ממש עובד, היא מגיעה בחבילה עם Slate, מה שהופך את הפעולה הזו לקלה למדי, כפי שגיליתי כאן,
כפי ש-Burke הדגיש פעמים רבות בפוסט שלו, עדיף להשתמש בפשטות ובתיאוריות במסמכים במקום בממשק משתמש טוב ובממשק נוצץ. אני אשתמש בעקרונות האלה ואנסה להפוך את נקודות הקצה שתועדו בעבר לתיאוריות ככל האפשר, על ידי שיחה עם מפתחים שעובדים כרגע על OpenMRS Webservices API ויצירת קשר עם הקהילה, בדיוק כמו שעשיתי בפוסט של ההרצאה כדי לאסוף תיאורים לסוגי המאפיינים של משאבי הטפסים שלא היו ברורים לי בבקשת העריכה שלי כאן. אני אעבוד על דברים בעדיפות גבוהה, אדבר עם החונכים שלי ואחליט אילו דברים באמת מוסיפים ערך למסמכים ושצריך קודם להשיג אותם.
הוספת תרחישים לדוגמה ככותרת מפורשת
בדקתי מסמכי תיעוד רבים של ממשקי API כדי להבין אותם, וראיתי שבכולם תרחישים לדוגמה מופיעים ככותרת מפורשת. אמנם יש לנו תרחישים לדוגמה שלא גלויים באופן מפורש, אבל הם משולבים במידה מסוימת בהגדרות ובדוגמאות שמופיעות אחרי ההגדרות של המשאבים והמשאבים המשניים. לדעתי כדאי להשקיע מאמץ כדי להפריד את התרחישים לדוגמה כישות נפרדת במסמכי התיעוד, כדי שמפתחים לא יצטרכו לחפש את התרחישים לדוגמה בהגדרות, אלא יוכלו פשוט לחפש אותם.
איתור תיעוד המשאבים החסרים
במצב הנוכחי של הפרויקט יש משאבים מפורטים כאן, אבל לאחר שראיתי את הגרסה העדכנית של מסמכי התיעוד בנושא סוואג, מצאתי משאבים רבים שאפשר להוסיף לחבילת המשאבים הנוכחית במסמכי ה-API הידידותיים ל-GitHub יחד עם התיאור שהושג עם משאבים אחרים במהלך העונה של Docs 2019. אדבר על הנושאים שצריך להוסיף למסמכים ואוסיף אותם בהתאם.
סיכום
אני חלק מקהילת OpenMRS כבר זמן מה. אני תורם/ת באופן פעיל בפרויקט Android Client, שבו יש לי אינטראקציה עם ממשקי ה-API לעיתים קרובות כדי ליצור אינטראקציה עם השרתים. לכן, אני חושב שאוכל לעבוד על הפרויקט הזה של הרחבת מסמכי התיעוד של ה-API די טוב,כי אני יכול לראות את העבודה שלי כמפתח ולבדוק אם היא באמת מקלה על העבודה של מפתחים אחרים. התחלתי להכיר את הכלים שמשמשים למאגר המסמכים הידידותי למשתמש שמתארח כאן. הוספת כמה פריטים למאגר הזה גם כדי להכיר את המאגר ואת הכלים, למשל slateUI. מכיוון שממשק API נחשב טוב ככל שהמסמכים שלו טובים, הייתי רוצה לשפר את מסמכי התיעוד של ממשקי ה-OpenMRS Rest API.
אעדכן על ההתקדמות באופן שבועי באמצעות פוסט בבלוג, כדי לקבל משוב מהקהילה. בנוסף, אעבוד בשיתוף פעולה הדוק עם המנטור שלי והקהילה כדי להפיק את המקסימום מתקופת התיעוד הזו.