פרויקט OpenMRS

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

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

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

OpenMRS

כתב טכני:

סאורב

שם הפרויקט:

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

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

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

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

מטרה עיקרית

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

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

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

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

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

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

לפניכם תקציר של ההצעה הנוכחית שבכוונתי לתאר :

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

תיאור מפורט

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

סיכום

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

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