หน้านี้มีรายละเอียดของโครงการเขียนเชิงเทคนิคที่ยอมรับใน Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- OpenMRS
- ผู้เขียนด้านเทคนิค:
- สุรภ์
- ชื่อโปรเจ็กต์:
- การขยายเอกสารประกอบ GitHub ที่เป็นมิตรกับผู้ใช้สำหรับ REST API
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
วัตถุประสงค์หลัก
ปรับปรุงเอกสารประกอบเกี่ยวกับ REST API ของ OpenMRS Sw โดยทั่วไปแล้ว REST API เพื่อเพิ่มคำแนะนำในการใช้งาน API
คำอธิบายโปรเจ็กต์
OpenMRS REST API เป็นหนึ่งในกลไกสำคัญที่ช่วยให้นักพัฒนาซอฟต์แวร์เข้าถึงข้อมูลจาก OpenMRS ได้ ตอนนี้เรามีเอกสารเกี่ยวกับ OpenMRS Webservices API ที่สร้างขึ้นโดยอัตโนมัติซึ่งอิงมาจาก Swouch และเอกสารแบบคงที่จาก GitHub อยู่แล้ว เราควรจะขยายเอกสารประกอบเกี่ยวกับ GitHub นั้นในซีซันของเอกสารฉบับนี้
ภาพรวมโดยสังเขป
หลังจากค้นคว้าข้อมูลเกี่ยวกับ OpenMRS Talk ตามที่ Burke แนะนำมาสักเล็กน้อย ผมก็ได้ทราบว่าโปรเจ็กต์นี้เริ่มต้นขึ้นเมื่อปี 2017 ในฐานะโครงการ GSOC Gayan Weerakutti ซึ่งมีวัตถุประสงค์หลักคือการปรับปรุงเอกสารประกอบที่มีอยู่ของ OpenMRS REST API โดยการปรับปรุงข้อมูลจำเพาะของ Swouch เอง และปรับปรุงวิธีการสร้างข้อกำหนดของ Swouch เองเพื่อสร้างเอกสารเวอร์ชันที่ดียิ่งขึ้น รายละเอียดที่เกี่ยวข้องทั้งหมดที่บรรลุผลสำเร็จในโครงการได้มีการสรุปไว้ที่นี่ในโพสต์พูดคุยของ OpenMRS นี้ ซึ่งมีประโยชน์มากทีเดียว
จากนั้นในปี 2019 โปรเจ็กต์นี้ก็ปรับปรุงใหม่ และเราก็เปลี่ยนจากการปรับแก้เอกสารของ Sweck เพื่อสร้างรูปแบบต่างๆ เกี่ยวกับเรื่องนี้ แต่เราได้พัฒนาเอกสารประกอบแบบคงที่ที่เหมาะกับ GitHub ซึ่งเราจะขยายบริการของเอกสารในซีซันนี้
ดังนั้น สรุปสั้นๆ เกี่ยวกับข้อเสนอโครงการในปัจจุบันที่ผมตั้งใจจะอธิบายคือ :
- ขอยกตัวอย่างภาษายอดนิยมบางภาษา (กล่าวถึง Java และ JavaScript โดยเฉพาะ)
- เพิ่มการรองรับ Playground สำหรับเอกสารแถบสเลทเช่นเดียวกับฟีเจอร์ "ลองออก"
- การปรับเปลี่ยนโครงสร้างภายในและปรับปรุงงานที่ทำจนเสร็จจนถึงปัจจุบัน
- ค้นหาและเพิ่มทรัพยากรที่ขาดหายไป
- เพิ่มคำอธิบายอีกเล็กน้อยในส่วนคอนโซลของเอกสาร
คำอธิบายโดยละเอียด
- ลองนึกถึงตัวอย่างในภาษาต่างๆ
เราขอแนะนำให้เพิ่มตัวอย่างใน Java ซึ่งจะใช้ SDK แล้วเพิ่มตัวอย่างการปรับปรุงซึ่งฉันคิดว่าจะทำให้เอกสารของเราเข้าใจรายละเอียดมากขึ้น เนื่องจากการเพิ่มตัวอย่างในอีกภาษาหนึ่ง เช่น JavaScript จะไม่ช่วยมากเท่ากับการเพิ่มตัวอย่างการแก้ไขเนื่องจากฉันใช้ REST API เหล่านี้ขณะทำงานกับไคลเอ็นต์ Android แบบ OpenMRS และไม่มีแหล่งข้อมูลให้ค้นหาเมื่อฉันต้องการความช่วยเหลือในการใช้อุปกรณ์ปลายทางสำหรับ Android โดยเฉพาะ และฉันจะสร้างตัวอย่างที่มีคุณภาพได้มากในตอนนี้ จากประสบการณ์ของฉันในการจัดการกับปลายทาง OpenMRS API ในไคลเอ็นต์ Android เราจะพูดคุยเรื่องนี้กับที่ปรึกษาของฉันและคิดหาวิธีตัดสินใจ นอกจากนี้ นอกเหนือจากการเพิ่มตัวอย่างสำหรับการดำเนินการที่รองรับแล้ว เรายังควรเพิ่มตัวอย่างการตรวจสอบสิทธิ์กับเซิร์ฟเวอร์ OpenMRS ในภาษาโปรแกรมบางภาษาด้วย ตอนนี้เรามีตัวอย่าง curl สำหรับกรณีนี้เท่านั้น
- การเพิ่มการรองรับ Playground สำหรับตัวอย่าง API การทดสอบ
ผมได้ใช้ฟีเจอร์นี้ในเอกสารประกอบชุดใหญ่ของ OpenMRS ที่โฮสต์อยู่ที่เซิร์ฟเวอร์การสาธิต และเป็นเครื่องมือที่สะดวกมากในการใส่เอกสารประกอบเกี่ยวกับ API เราได้หาข้อมูลไว้ที่นี่แล้ว การฝังข้อมูลจำเพาะของ Swouch-UI ลงในเอกสารแบบคงที่ฉบับปัจจุบันนั้นไม่ยากเลย การใช้ตัวสลับแสดงการซ่อน และการใช้โค้ดเอกสารกริชปัจจุบันที่เรามีอยู่ วิธีนี้ทำให้เราสามารถมั่นใจได้ว่าฟีเจอร์ทดลองยังคงใช้งานได้ตามข้อกำหนดของ API ในปัจจุบัน นี่เป็นวิธีหนึ่งที่ทำให้เราเชื่อว่าเราสามารถผสานรวมฟีเจอร์ Play เข้ากับเอกสารฉบับแก้ไขฉบับปัจจุบันได้
- การปรับเปลี่ยนโครงสร้างภายในและปรับปรุงงานที่ทำจนเสร็จจนถึงปัจจุบัน
กำลังตรวจสอบตัวอย่าง Curl ปัจจุบัน
ส่วนนี้เป็นหนึ่งในประเด็นสำคัญสำหรับโปรเจ็กต์นี้ ปัจจุบันมีเพียงตัวอย่าง Curl เท่านั้นในเอกสาร GitHub API ซึ่งบางฉบับไม่สามารถเรียกใช้โดยตรงในเซิร์ฟเวอร์สาธิตเพื่อตรวจสอบจากเบราว์เซอร์โดยตรง ฉันจะทดสอบปลายทางปัจจุบันทั้งหมดและดูแลรักษาเอกสารง่ายๆ ที่มีคำตอบของตัวอย่าง curl ต่างๆ ที่เราได้รับจากการเรียกใช้คำขอ curl เหล่านั้น ฉันจะใช้ Postman เพิ่มเติมจากฟีเจอร์ระบบการลองเสมือนจริงในเอกสารประกอบสุดกล่อมเพื่อทำงานนี้ให้สำเร็จ หากจำเป็น
ไม่มีการตอบกลับจาก API ในตัวอย่างบางส่วน
มีการเพิ่มคำตอบบางรายการสำหรับตัวอย่าง curl ที่แสดง แต่ตัวอย่าง curl บางรายการไม่มีการตอบกลับ ฉันคิดว่าแม้ว่าคำตอบจะไม่ได้รายละเอียดซึ่งมักเป็นการดำเนินการต่างๆ เช่น การล้างทรัพยากร เราควรมีตัวอย่างการตอบกลับ API ของ JSON แม้ว่าเราจะได้บันทึกโค้ดตอบกลับที่เป็นไปได้ทั้งหมดแล้วและเหตุผลที่ควรใช้ ฉันคิดว่านี่จะทำให้ตัวอย่างในเอกสาร API มีความสม่ำเสมอมากขึ้น !!
ตัวอย่างการทํางานของการดําเนินการต่างๆ ขาดหายไป
ฉันคิดว่านี่จะเป็นส่วนสำคัญที่สุดของการเปลี่ยนโครงสร้างงานที่ทำไปแล้วก่อนหน้านี้ในเอกสาร API มีตัวอย่างที่เป็นรูปธรรมในเอกสารซึ่งสามารถสั่งการด้วย cURL ได้โดยตรง แต่บางตัวอย่างก็มีลักษณะเป็นนามธรรมที่อ้างอิงถึงนักพัฒนาซอฟต์แวร์ที่มีประสบการณ์ได้เป็นอย่างดี แต่ก็เหลือแค่ตัวอย่างใหม่ที่ไม่น่ารำคาญ อย่างที่ผมได้รวบรวมมาจากโพสต์นี้ใน OpenMRS มาว่าตัวอย่างที่ดีนั้นไร้ค่า ดังนั้น นอกจากการเพิ่มตัวอย่างงานแล้ว เราสามารถรองรับการไฮไลต์ไวยากรณ์ ซึ่งที่จริงแล้วไม่ได้ทำงานมากนัก แต่มีแถบสเลททำให้วิธีนี้ค่อนข้างง่าย
อย่างที่ Burke ได้เน้นย้ำหลายครั้งในโพสต์ของเขาว่า ต้องการความเรียบง่ายและสื่อความหมายในเอกสารแทน UI ที่ดีและอินเทอร์เฟซที่ชัดเจน ฉันจะปฏิบัติตามหลักการเหล่านี้และพยายามทำให้ปลายทางที่บันทึกไว้ก่อนหน้านี้อธิบายได้ดีที่สุด โดยการพูดคุยกับนักพัฒนาที่กำลังใช้งาน OpenMRS Webservices API และมีส่วนร่วมกับชุมชน เหมือนกับที่ผมได้เขียนในโพสต์การพูดคุยเพื่อเก็บรวบรวมคำอธิบายสำหรับแอตทริบิวต์ของแบบฟอร์มที่จะชี้แจงเกี่ยวกับประเภทแอตทริบิวต์ต่างๆ ที่ฉันใช้ ฉันจะทำงานในลำดับความสำคัญที่เหมาะสม พูดคุยกับที่ปรึกษา และตัดสินใจว่าอะไรคือสิ่งที่เพิ่มคุณค่าให้กับเอกสารได้จริงๆ และต้องทำให้เสร็จก่อน
การเพิ่ม Use Case เป็นบรรทัดแรกอย่างชัดแจ้ง
ผมเคยเห็นเอกสารประกอบเกี่ยวกับ API มากมาย เลยเข้าใจ และเห็นว่าทุก Use Case เป็นบรรทัดแรกที่ชัดเจน แม้ว่าเราจะมี Use Case ที่ไม่ได้แสดงให้เห็นอย่างชัดเจนนัก โดยมีการรวมกันอยู่ในคำจำกัดความและตัวอย่างที่ตามมาหลังจากให้คำจำกัดความแหล่งข้อมูลและแหล่งข้อมูลย่อยแล้ว ผมคิดว่าเราควรแยก Use-Cases ออกเป็นส่วนๆ ในเอกสารประกอบเพื่อให้นักพัฒนาซอฟต์แวร์ไม่ต้องค้นหาเพียงคําจํากัดความในคําจํากัดความ
ค้นหาและบันทึกข้อมูลทรัพยากรที่ขาดหายไป
สถานะของโปรเจ็กต์ปัจจุบันมีแหล่งข้อมูลแสดงไว้ที่นี่ แต่เมื่อเห็นเอกสารประกอบฉบับสุดโต่งฉบับล่าสุดที่นี่ เราก็อาจหาแหล่งข้อมูลมากมายที่สามารถเพิ่มในชุดทรัพยากรปัจจุบันในเอกสาร API ที่ใช้งานกับ GitHub พร้อมคำอธิบายที่สามารถทำได้โดยใช้แหล่งข้อมูลอื่นในระหว่างฤดูกาลของเอกสาร 2019 เราจะพูดถึงหัวข้อที่ต้องเพิ่มลงในเอกสารและเพิ่มตามความเหมาะสม
บทสรุป
ฉันอยู่ในชุมชน OpenMRS มาระยะหนึ่งแล้ว ฉันเป็นผู้มีส่วนร่วมในโปรเจ็กต์ไคลเอ็นต์ Android ซึ่งฉันโต้ตอบกับ API อยู่บ่อยๆ เพื่อโต้ตอบกับเซิร์ฟเวอร์ ดังนั้น ฉันรู้สึกว่าเราสามารถทำโปรเจ็กต์นี้เพื่อขยายเอกสาร API ได้ค่อนข้างดี เนื่องจากฉันสามารถดูงานของฉันในฐานะนักพัฒนาซอฟต์แวร์ได้ด้วยตัวเอง และประเมินว่าเป็นการช่วยลดงานของนักพัฒนาซอฟต์แวร์รายอื่นได้หรือไม่ ฉันเริ่มคุ้นเคยกับเครื่องมือที่ใช้สำหรับที่เก็บเอกสารที่ใช้ง่ายที่โฮสต์ที่นี่แล้ว ฉันจึงได้มีส่วนร่วมหลายอย่างกับที่เก็บนี้ด้วย เพื่อสร้างความคุ้นเคยกับที่เก็บและเครื่องมือ เช่น API ของ API ที่คิดว่าเป็นการปรับปรุง API ของ API ที่คิดว่าเป็นการปรับปรุง API ก็น่าจะทำให้คุณคุ้นเคยกับที่เก็บและเครื่องมือของ API ได้เช่นกัน
ฉันจะแจ้งความคืบหน้าทุกสัปดาห์ด้วยโพสต์การพูดคุย ซึ่งจะช่วยให้ได้รับความคิดเห็นจากชุมชนและประสานงานอย่างใกล้ชิดกับที่ปรึกษาและชุมชนของฉันเพื่อให้ได้รับประโยชน์สูงสุดจากระยะเวลาในเอกสาร