โปรเจ็กต์ OpenMRS

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

สรุปโปรเจ็กต์

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

OpenMRS

นักเขียนเชิงเทคนิค

Saurabh

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

การขยายเอกสารประกอบของ GitHub ที่ใช้งานง่ายสำหรับ REST API

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

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

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

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

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

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

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

ภาพรวมโดยย่อ

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

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

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

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

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

1. ลองคิดตัวอย่างในภาษาต่างๆ

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

1. เพิ่มการรองรับการทดสอบตัวอย่าง API ใน Playgroud

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

1. การจัดระเบียบโค้ดใหม่และปรับปรุงงานที่ทําจนถึงตอนนี้

ตรวจสอบตัวอย่าง curl ปัจจุบัน

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

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

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

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

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

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

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

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

1. การค้นหาและบันทึกแหล่งข้อมูลที่หายไป

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

บทสรุป

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

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