โปรเจ็กต์ OpenMRS

หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs

ข้อมูลสรุปของโปรเจ็กต์

องค์กรโอเพนซอร์ส:

OpenMRS

ผู้เขียนด้านเทคนิค:

โซราภ

ชื่อโปรเจ็กต์:

การขยายเอกสารประกอบเกี่ยวกับ GitHub ที่เป็นมิตรกับผู้ใช้สำหรับ REST API

ระยะเวลาของโปรเจ็กต์:

ระยะเวลามาตรฐาน (3 เดือน)

คำอธิบายโปรเจ็กต์

วัตถุประสงค์หลัก

ปรับปรุงเอกสารประกอบ REST API ของ OpenMRS Swagger เพื่อเพิ่มคำแนะนำเกี่ยวกับการใช้ API

คำอธิบายโครงการ

OpenMRS REST API เป็นหนึ่งในกลไกหลักสำหรับนักพัฒนาซอฟต์แวร์ในการเข้าถึงข้อมูลจาก OpenMRS นอกจากนี้ เรายังมีเอกสารเกี่ยวกับ OpenMRS Webservices API ที่สร้างขึ้นโดยอัตโนมัติจาก Swunch และเอกสารแบบคงที่ที่ใช้ GitHub อยู่แล้วด้วย เราควรที่จะขยายเอกสารประกอบตาม GitHub นั้นในซีซันของเอกสารฉบับนี้

ภาพรวมโดยสังเขป

หลังจากค้นคว้าเกี่ยวกับ OpenMRS Talk ตามที่ Burke แนะนำไปสักเล็กน้อย ผมได้รู้ว่าโปรเจ็กต์นี้เริ่มต้นขึ้นในปี 2017 ในฐานะโครงการ GSOC สำหรับ Gayan Weerakutti โดยมีวัตถุประสงค์หลักคือการปรับปรุงเอกสารประกอบที่มีอยู่ของ OpenMRS REST API, ด้วยการปรับปรุงข้อกำหนด Swurge และปรับปรุงวิธีการสร้างข้อกำหนดของ Swurge เพื่อสร้างเอกสารประกอบที่สับเปลี่ยนขึ้นมาเอง รายละเอียดที่เกี่ยวข้องทั้งหมดที่บรรลุในโครงการนั้นสรุปไว้ ณ ที่นี้ในบทความการสนทนา OpenMRS นี้ ซึ่งมีประโยชน์มาก

จากนั้นในปี 2019 โปรเจ็กต์นี้ก็ได้รับการปรับปรุงใหม่ และเราก็เปลี่ยนจากเอกสารของ Swurge มาปรับเปลี่ยนการสร้างรูปแบบใหม่ๆ ในเรื่องนี้ แต่เราได้พัฒนาเอกสารที่ใช้งานง่ายสำหรับ GitHub แบบคงที่ ซึ่งเรากำลังจะขยายให้กับเอกสารซีซันนี้

ดังนั้น สรุปสั้นๆ ของข้อเสนอโครงการปัจจุบันที่เราตั้งใจจะอธิบายคือ :

1. ยกตัวอย่างในภาษายอดนิยมบางภาษา (กล่าวถึง java และ javascript โดยเฉพาะ)
2. เพิ่มการรองรับ Playground สำหรับเอกสารแถบสเลทเช่นเดียวกับฟีเจอร์ "ลองออก"
3. การปรับโครงสร้างและการปรับปรุงงานที่ทำจนถึงปัจจุบัน
4. การค้นหาและเพิ่มทรัพยากรที่ขาดหายไป
5. เพิ่มคำอธิบายอีกเล็กน้อยในส่วนคอนโซลของเอกสาร

คำอธิบายโดยละเอียด

1. ลองนึกถึงตัวอย่างในภาษาต่างๆ

เราขอแนะนำให้เพิ่มตัวอย่างใน Java ซึ่งจะใช้ SDK เป็นหลัก แล้วเพิ่มตัวอย่างการดัดแปลงซึ่งฉันคิดว่าจะทำให้เอกสารมีข้อมูลเชิงลึกมากขึ้น เนื่องจากการเพิ่มตัวอย่างในอีกภาษาหนึ่ง เช่น JavaScript จะไม่ช่วยมากเท่ากับการเพิ่มตัวอย่าง Retrofit เนื่องจากฉันใช้ REST API เหล่านี้ขณะทำงานกับไคลเอ็นต์ Android ของ OpenMRS และไม่มีทรัพยากรให้ค้นหาทุกครั้งที่ฉันต้องการความช่วยเหลือในการใช้ปลายทางสำหรับ Android โดยเฉพาะ และจะได้ทำตัวอย่างที่มีคุณภาพที่นี่ เพราะมีประสบการณ์ในการจัดการกับปลายทาง OpenMRS API ในไคลเอ็นต์ Android เราจะปรึกษาเรื่องนี้กับ Mentor และหารือกันว่าตัดสินใจอย่างไร นอกจากนี้ นอกเหนือจากการเพิ่มตัวอย่างสำหรับการดำเนินการที่รองรับแล้ว เรายังควรเพิ่มตัวอย่างสำหรับการตรวจสอบสิทธิ์กับเซิร์ฟเวอร์ OpenMRS ในภาษาโปรแกรมบางภาษาด้วย ปัจจุบันเรามีแค่ตัวอย่าง Curl สำหรับกรณีนี้

1. การเพิ่มการรองรับ Playground สำหรับตัวอย่าง API การทดสอบ

เราได้ใช้ฟีเจอร์นี้ในเอกสารประกอบฉบับเก่าของ OpenMRS ที่โฮสต์ในเซิร์ฟเวอร์สาธิตแล้ว และเป็นเครื่องมือที่สะดวกมากสำหรับใช้ในเอกสาร API เราศึกษาข้อมูลมาบ้างแล้ว และการฝังข้อมูลจำเพาะของ Swagger-UI ลงในเอกสารแบบคงที่ฉบับปัจจุบันนั้นไม่ยากเลย การใช้ปุ่มสลับแสดงการซ่อนและใช้รหัสเอกสารแบบสับเปลี่ยนที่เรามีอยู่ วิธีนี้ทำให้เรามั่นใจได้ว่าฟีเจอร์ทดลองใช้จะยังคงใช้งานได้ต่อไปตามข้อกำหนดของ API ในปัจจุบัน นี่เป็นวิธีหนึ่งที่ทำให้เราเชื่อว่าเราสามารถผสานรวมฟีเจอร์ Play Store เข้ากับเอกสารประกอบแบบคงที่ฉบับปัจจุบันได้

1. การปรับโครงสร้างและการปรับปรุงงานที่ทำจนถึงปัจจุบัน

กำลังตรวจสอบตัวอย่าง Curl ปัจจุบัน

ส่วนนี้เป็นประเด็นสำคัญอย่างหนึ่งของโครงการนี้ในปีนี้ ปัจจุบันมีเพียงตัวอย่าง curl เท่านั้นที่อยู่ในเอกสาร GitHub API ซึ่งบางฉบับไม่สามารถเรียกใช้โดยตรงในเซิร์ฟเวอร์สาธิตเพื่อตรวจสอบจากเบราว์เซอร์โดยตรง ฉันจะทดสอบปลายทางปัจจุบันทั้งหมดและคงเอกสารง่ายๆ ที่มีคำตอบของตัวอย่าง curl ต่างๆ ที่เราได้รับจากการเรียกใช้คำขอ curl เหล่านั้น ฉันจะใช้ Postman เพิ่มเติมจากฟีเจอร์ทดลองใช้ที่มีอยู่ในเอกสารสุดหล่อเพื่อทำงานนี้ให้สำเร็จหากจำเป็น

ไม่มีการตอบกลับ API ในตัวอย่างบางรายการ

มีการเพิ่มคำตอบบางรายการสำหรับตัวอย่าง curl นำเสนอ แต่ตัวอย่าง curl บางส่วนไม่มีคำตอบ ฉันคิดว่าแม้ว่าคำตอบจะไม่ได้ละเอียดขึ้น ซึ่งโดยปกติจะเป็นการดำเนินการอย่างการลบทรัพยากรออก เราควรมีตัวอย่างการตอบกลับ JSON API แม้ว่าเราจะได้จัดทำเอกสารโค้ดตอบกลับที่เป็นไปได้ทั้งหมดและเหตุผลที่ทำให้ได้ แล้ว แต่ฉันคิดว่าจะทำให้ตัวอย่างในเอกสาร API เหมือนกันมากขึ้น !!

ไม่มีตัวอย่างการทำงานสำหรับการดำเนินการต่างๆ

ฉันคิดว่านี่จะเป็นส่วนสำคัญที่สุดของการปรับโครงสร้างงานที่ทำก่อนหน้านี้ในเอกสารประกอบของ API ใหม่ มีตัวอย่างที่เป็นรูปธรรมในเอกสาร ซึ่งสามารถดำเนินการได้โดยตรงด้วย cURL แต่บางรายการเป็นเพียงนามธรรมที่อ้างอิงถึงนักพัฒนาซอฟต์แวร์ที่มีประสบการณ์ได้เป็นอย่างดี แต่ก็ทำให้ผู้มาใหม่รู้สึกรำคาญใจ อย่างที่ผมได้รวบรวมจากโพสต์นี้ใน OpenMRS บอกว่าตัวอย่างที่ดีไม่มีคุณค่า ดังนั้นนอกจากการเพิ่มตัวอย่างงานแล้ว เรายังสามารถสนับสนุนการไฮไลต์ไวยากรณ์ ซึ่งไม่ค่อยได้ผลมากนัก แถมยังมาพร้อมกับแถบสเลทซึ่งทำให้วิธีนี้ง่ายมาก ซึ่งเราค้นพบด้วย

ดังที่ Burke ได้เน้นย้ำหลายครั้งในโพสต์ของเขาว่า ต้องการความเรียบง่ายและสื่อความหมายในเอกสารแทน UI ที่ดีและอินเทอร์เฟซที่สวยเด่น ผมจะทำตามหลักการเหล่านี้ และพยายามทำให้ปลายทางที่ระบุไว้ก่อนหน้านี้อธิบายรายละเอียดให้มากที่สุด โดยพูดคุยกับนักพัฒนาที่กำลังทำงานกับ OpenMRS Webservices API และมีส่วนร่วมกับชุมชน เหมือนกับที่ผมได้อธิบายเกี่ยวกับประเภทแอตทริบิวต์สำหรับฟอร์มที่นี่ ซึ่งเขียนอธิบายเกี่ยวกับประเภทแอตทริบิวต์สำหรับฟอร์มที่นี่ ฉันจะทำงานที่สำคัญมากๆ โดยคำนึงถึงการพูดคุยและปรึกษากับ Mentor และตัดสินใจสิ่งที่จะเพิ่มคุณค่าจริงๆ ในเอกสารและต้องดำเนินการให้สำเร็จก่อน

การเพิ่ม Use Case เป็นบรรทัดแรกอย่างชัดแจ้ง

เราได้เห็นเอกสารประกอบเกี่ยวกับ API มากมายเพื่อทำความเข้าใจและเห็นว่าทุก Use Case เป็นบรรทัดแรกที่ชัดเจน แม้ว่าเราจะมี Use Case ที่ไม่ได้ปรากฏให้เห็นอย่างชัดเจน ซึ่งค่อนข้างรวมกันอยู่ในคำจำกัดความและตัวอย่างที่ตามมาหลังจากคำจำกัดความของทรัพยากรและทรัพยากรย่อยแล้ว ผมคิดว่าเราควรแยก Use Case ออกเป็นเอนทิตีที่แยกต่างหากในเอกสารมากกว่า นักพัฒนาซอฟต์แวร์จึงไม่ต้องค้นหากรณีการใช้งานเหล่านี้จริงๆ

1. การค้นหาและบันทึกทรัพยากรที่หายไป

   สถานะของโปรเจ็กต์ปัจจุบันมีแหล่งข้อมูลแสดงไว้ที่นี่ แต่เมื่อดูเอกสารประกอบล่าสุดที่นี่ ทำให้เราสามารถหาทรัพยากรมากมายที่สามารถเพิ่มลงในชุดทรัพยากรปัจจุบันในเอกสาร API ที่ใช้งานกับ GitHub พร้อมคำอธิบายที่สามารถทำได้เมื่อใช้แหล่งข้อมูลอื่นๆ ในซีซันของเอกสาร 2019 เราจะพูดถึงหัวข้อที่ต้องเพิ่มลงในเอกสารและเพิ่มตามความเหมาะสม

บทสรุป

ฉันเป็นส่วนหนึ่งของชุมชน OpenMRS มาสักระยะหนึ่งแล้ว ฉันเป็นผู้ร่วมให้ข้อมูลที่ใช้งานอยู่ในโครงการไคลเอ็นต์ Android ซึ่งฉันโต้ตอบกับ API บ่อยครั้งเพื่อโต้ตอบกับเซิร์ฟเวอร์ ดังนั้น ฉันรู้สึกว่าเราสามารถดำเนินโครงการนี้เพื่อขยายการใช้งานเอกสาร API ได้ค่อนข้างดี เนื่องจากฉันสามารถดูงานของฉันในฐานะนักพัฒนาซอฟต์แวร์ด้วยตนเอง และประเมินว่าจะทำให้การทำงานของนักพัฒนาซอฟต์แวร์คนอื่นง่ายขึ้นหรือไม่ ฉันคุ้นเคยกับเครื่องมือที่ใช้สำหรับที่เก็บเอกสาร API ที่ใช้งานง่ายซึ่งโฮสต์ที่นี่ ฉันจึงได้มีส่วนร่วมหลายอย่างกับที่เก็บนี้เช่นกัน เพื่อสร้างความคุ้นเคยกับที่เก็บและเครื่องมือ เช่น การพัฒนา API ของ ResM คือความชื่นชอบ API ของ API

ฉันจะแจ้งความคืบหน้าทุกสัปดาห์ด้วยโพสต์การพูดคุย ซึ่งจะช่วยให้ชุมชนได้รับความคิดเห็นและทำงานร่วมกันอย่างใกล้ชิดกับที่ปรึกษาและชุมชนของฉันเพื่อให้ใช้ประโยชน์จากเอกสารประกอบในช่วงนี้ได้อย่างเต็มที่