פרויקט OpenMRS

דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.

סיכום הפרויקט

ארגון הקוד הפתוח:

OpenMRS

כתב טכני:

סאורבה

שם הפרויקט:

הרחבת התיעוד של GitHub ל-API ל-REST

אורך הפרויקט:

אורך רגיל (3 חודשים)

תיאור הפרויקט

מטרה עיקרית

אפשר לשפר את מסמכי התיעוד של API ל-REST מסוג OpenMRS שמבוססים על Swagger, כדי להוסיף הנחיות לשימוש ב-API.

תיאור הפרויקט

OpenMRS REST API הוא אחד ממנגנוני המפתחות שבאמצעותם מפתחים יכולים לגשת לנתונים מ-OpenMRS. כבר יש תיעוד שנוצר אוטומטית ומבוסס 'סוואג'ר' של OpenMRS Webservices API ותיעוד סטטי שמבוסס על GitHub. אנחנו אמורים להרחיב את התיעוד שמבוסס על GitHub בעונה הזו של Docs.

סקירה כללית קצרה

לאחר שפע המחקר על OpenMRS Talk כפי שהציע בורק, גיליתי שהפרויקט הזה התחיל ב-2017 כפרויקט GSOC. המטרה העיקרית של Gayan Weerakutti היא לשפר את התיעוד הקיים של OpenMRS REST API, על ידי שיפור מפרט Swagger ושיפורים באופן היצירה של מפרט Swagger, כך שתיווצר גרסה טובה יותר של המסמכים המתחמקים. כל הפרטים הרלוונטיים שהושגו בפרויקט סוכמו כאן בפוסט של שיחות על OpenMRS זה, והיו שימושיים למדי.

לאחר מכן, ב-2019, חוּדשנו את הפרויקט הזה ועברנו משינויים קלים בתיעוד של Swagger שהובילו ליצירת וריאציות. במקום זאת, פיתחנו תיעוד סטטי וידידותי ל-GitHub שנרחיב בעונה הזו של Docs.

אז בקצרה של הצעת הפרויקט הנוכחית שאני מתכוון לתאר :

1. ריכזנו כאן דוגמאות בכמה שפות פופולריות (ספציפיות, Java ו-JavaScript).
2. הוספת תמיכה במגרש משחקים לתיעוד של אפור צפחה, בדיוק כמו התכונה 'לנסות-out' של Swagger.
3. ארגון מחדש ושיפור של העבודה שהכנתם עד עכשיו.
4. חיפוש והוספה של המשאבים החסרים.
5. אנחנו מוסיפים עוד קצת תיאור לקטע של המסוף ב-Docs

תיאור מפורט

1. חשוב על דוגמאות בשפות שונות.

הייתי מציע להוסיף דוגמאות ב-Java שתתבסס על SDK, ואז להוסיף דוגמאות רטרואקטיביות שלדעתי יוסיפו עומק לתיעוד, כי הוספת דוגמאות בשפה אחת נוספת כמו JavaScript לא תעזור באותה מידה כמו הוספת דוגמאות רטרואקטיביות, כי השתמשתי בממשקי ה-API האלה ל-REST במהלך העבודה על OpenMRS Android Client, ולא היו משאבים שאני יכול לחפש בהם אם אצטרך לקבל עזרה בשימוש בנקודות הקצה (endpoints) במיוחד ב-Android. לאור הניסיון שלי בכתיבת נקודות קצה (endpoint) של OpenMRS API בלקוח Android, אוכל לתת כאן כמה דוגמאות איכותיות. אדבר על זה עם המנטורים שלי ואעבוד על מה שיוחלט. כמו כן, מלבד הוספת דוגמאות לפעולות הנתמכות, יש להוסיף דוגמאות לאימות מול שרתי OpenMRS בשפות תכנות מסוימות גם כן. כרגע יש לנו רק דוגמאות curl בשביל זה.

1. הוספת תמיכה ב-Playground לבדיקת דוגמאות של ממשקי API

השתמשתי בתכונה הזו בתיעוד המרשים של OpenMRS שמתארח בשרת ההדגמה, וזה כלי נוח לשימוש בכל תיעוד של ממשק ה-API. חקרתי קצת כאן ולא קשה להטמיע את מפרט Swagger-UI בתיעוד הסטטי הנוכחי. שימוש במתגי ההסתרה של תוכנית ההסתרה ושימוש בקוד התיעוד הקיים שלנו בנושא 'סוואג'. כך אנחנו יכולים אפילו להבטיח שהתכונה הניסיונית תישאר פעילה בהתאם למפרטים הנוכחיים של ה-API. זו אחת הדרכים שבהן לדעתי נוכל לשלב תכונות של מגרש משחקים בתיעוד הסטטי הנוכחי שלנו.

1. ארגון מחדש ושיפור של העבודה שכבר נעשתה עד עכשיו

בדיקת הדוגמאות הנוכחיות ל-Curl

הקטע הזה הוא אחד הנושאים המרכזיים של הפרויקט השנה. בשלב זה, רק דוגמאות curl נמצאות במסמכי API של GitHub. את חלקם לא ניתן להריץ ישירות בשרת ההדגמה כדי לבדוק ישירות מהדפדפן. אבדוק את כל נקודות הקצה הקיימות ואשמור מסמך פשוט עם תשובות שונות ל-Curls לדוגמה שאנחנו מקבלים על הרצת בקשות ה-Curl האלה. אם יהיה צורך, אני אשתמש ב-Postman בנוסף לתכונת ההתנסות המובנית בתיעוד המוכר כדי לבצע את המשימה הזו.

חסרות תגובות של ה-API בחלק מהדוגמאות

חלק מהתשובות נוספו עבור הדוגמאות הנוכחיות של curl, אבל לחלק מהדוגמאות של curl אין תשובות. לדעתי, גם אם התשובות לא מילוליות, מה שקורה בדרך כלל בפעולות כמו מחיקת המשאב, הייתה לנו דוגמה ל-JSON API Response, למרות שתיעדנו את כל קודי התגובה האפשריים ואת הסיבה לקבל אותם. זה יהפוך את הדוגמאות שבמסמכי ה-API לאחידות יותר!

חסרות דוגמאות עבודה לפעולות שונות

אני חושב שזה החלק החשוב ביותר בארגון של העבודה שכבר הושלמה במסמכי ה-API. יש דוגמאות קונקרטיות במסמכי התיעוד שניתן לבצע ישירות באמצעות cURL, אבל חלק מהן מופשטות במידה מסוימת שנותנות מענה טוב למפתחים מנוסים, אבל משאירים את המפתחים החדשים במצב מטריד. כפי שיכולתי להבין מהפוסט הזה ב-OpenMRS לדבר על כך שדוגמאות טובות הן יקרות ערך, לכן מלבד הוספת דוגמאות של עבודה אנחנו יכולים לתמוך בהדגשת תחביר שאכן לא עובדת. כמעט כל זה מגיע בחבילה עם צפחה, כך שקל לעשות את זה כמו שגיליתי כאן,

שבורק הדגיש פעמים רבות בפוסט שלו את הפשטות ואת התיאוריות במסמכים במקום ממשק משתמש טוב וממשק זוהר, וכך אפעל לפי העקרונות האלה ואנסה ליצור את נקודות הקצה שתועדו קודם בצורה תיאורית ככל האפשר, ולדבר עם מפתחים שעובדים כרגע על ממשק ה-API של OpenMRS לשירותי אינטרנט, בדיוק כמו שעשיתי בפוסט הזה כדי לאסוף פרטים לגבי סוגי מאפיינים שלא היו ברורים עבור הטפסים. הייתי עובדת על דברים עם עדיפות, משוחחת עם המנטורים שלי ומחליטה מהם הדברים שבאמת מוסיפים ערך למסמכי התיעוד וחשוב להשלים אותם קודם.

הוספת תרחישים לדוגמה ככותרת בוטה

ראיתי הרבה תיעוד של ממשקי API כדי להבין אותם, וראיתי שלכולם יש תרחישים לדוגמה ככותרת מפורשת. עם זאת, יש תרחישים לדוגמה שלא ניתן לראות באופן מפורש, אבל שילובי ההגדרות והדוגמאות שמופיעות אחרי ההגדרות של המשאבים ומשאבי המשנה צריך להתאמץ להפריד בין מקרי השימוש כישות נפרדת בתיעוד, כדי שהמפתחים יוכלו פשוט לחפש לפי ההגדרות.

1. איתור ותיעוד של המשאבים החסרים

   במצב הפרויקט הנוכחי יש פירוט של המשאבים, אבל בגרסה האחרונה של התיעוד הרלוונטי, יכולתי לחשוב על משאבים רבים שאפשר להוסיף לחבילת המשאבים הנוכחית במסמכי ה-API הידידותי ל-GitHub ולתאר אותם איך ניתן היה להשיג עם משאבים אחרים במהלך העונה של Docs 2019. אדבר על הנושאים שצריך להוסיף למסמכים ואוסיף אותם בהתאם.

סיכום

אני חברה בקהילת OpenMRS כבר זמן מה. אני משתתף/ת באופן פעיל בפרויקט Android Client שבו יש לי אינטראקציה לעיתים קרובות עם ממשקי API כדי לקיים אינטראקציה עם השרתים. לאור זאת, לדעתי יש לי אפשרות לעבוד על הפרויקט הזה של הרחבת מסמכי ה-API בעצמי,מכיוון שאני יכול לראות את העבודה שלי בעצמי כמפתח ולהעריך אם היא מפשטת את עבודתם של מפתחים אחרים או לא. למדתי להכיר את הכלים שמשמשים למאגר התיעודי ידידותי למשתמש שמתארח כאן, לכן הוספתי כמה פרטים למאגר הזה כדי להכיר את ממשקי ה-API והכלים שבהם אני משתמש, כך ש-SlateUI הוא רעיון לשיפור ה-API.

אדאג לעדכן את ההתקדמות מדי שבוע באמצעות פוסט שיחה שיעזור לקבל את המשוב מהקהילה ולעבוד בשיתוף פעולה הדוק עם המנטור ועם הקהילה שלי כדי להפיק את המרב מתקופת התיעוד הזו.