หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- OpenMRS.org
- ผู้เขียนด้านเทคนิค:
- batbrain7
- ชื่อโปรเจ็กต์:
- เอกสารประกอบเกี่ยวกับ OpenMRS REST API
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ฉันจะแบ่งข้อเสนอออกเป็นส่วนต่างๆ และดำเนินการตามขั้นตอน เช่น เอกสารประกอบของ Google Maps API และเอกสาร GitHub API
นอกจากนี้ เราขอเสนอโครงสร้าง Readme สำหรับเอกสาร API ที่ดำเนินการโดย Realworld.io ด้วย https://github.com/gothinkster/realworld/tree/master/api
โดยส่วนตัวแล้ว เราพบว่าเอกสารนี้อ่านเข้าใจและใช้งานได้ง่ายมาก
ข้อเสนอของฉันหลักๆ แล้วจะประกอบด้วย 3 ส่วน คือ
ส่วนที่เกริ่นนำสั้นๆ เกี่ยวกับ API, OpenMRS และวิธีใช้ API รวมถึงสิ่งที่จะเกิดขึ้นหลังจากนั้น
วิธีรับคีย์ API และการตรวจสอบสิทธิ์ที่จำเป็นโดยทั่วไปเพื่อส่งคำขอ API ซึ่งจะประกอบด้วยตัวอย่างประเภทการตรวจสอบสิทธิ์ที่แสดงใน API และคีย์และค่าที่จำเป็นต้องระบุ รวมถึงประเภทค่าที่ได้รับการยอมรับซึ่งสอดคล้องกับคีย์ในส่วนนั้น ตัวอย่างโค้ดในทุกภาษาจะช่วยและล้างวิธีเขียนส่วนหัวและรูปแบบการตอบกลับ และพารามิเตอร์การค้นหาอื่นๆ ใน API
ประเภทการตอบกลับที่ API ดึงข้อมูล, ประเภทของ JSON หรือผลการค้นหาประเภทอื่นๆ ที่ API แสดงผล
เส้นทาง API ต่างๆ และพารามิเตอร์ทั้งหมดที่ต้องส่งไปพร้อมกับเส้นทางเหล่านั้น ส่วนหัว และอื่นๆ API แต่ละรายการจะได้รับความช่วยเหลือจากตัวอย่างโค้ดในภาษาต่างๆ 2 - 3 ภาษาที่อธิบายวิธีสร้างคำขอในขณะที่เขียนโค้ดสำหรับ API นั้นๆ นอกเหนือจากรหัสข้อผิดพลาดทั่วไปที่อาจพบได้กับ API แต่ละรายการ
ต่อไปนี้เป็นแนวคิดทั่วไปของวิธีการกำหนดเอกสารประกอบสำหรับ REST API
กำหนดการสำหรับโปรเจ็กต์มีดังนี้
1 สิงหาคม - 1 กันยายน
ทำความคุ้นเคยกับที่ปรึกษาและพูดคุยรายละเอียดเพิ่มเติมเกี่ยวกับเอกสารที่ต้องใช้ในส่วนต่างๆ ของฐานของโค้ด และพูดคุยถึงวิธีการเจาะลึกในเอกสารระดับต่ำเทียบกับระดับสูง นอกจากนี้ ฉันจะใช้เวลาทำความเข้าใจฐานของโค้ดและศึกษาแนวคิดเพื่อจัดทำเอกสารให้ดียิ่งขึ้น
สัปดาห์ที่ 1 และ 2
เราจะปรับปรุงและขยายคู่มือสำหรับผู้ให้ข้อมูลร่วมกัน เราจะปรับปรุงเอกสารประกอบเกี่ยวกับวิธีสร้างซอร์สโค้ด ฉันจะเพิ่มส่วนผู้จัดทำเอกสารเกี่ยวกับวิธีที่ผู้ร่วมให้ข้อมูลรายใหม่จะช่วยเหลือในเอกสารต่างๆ ด้วย ฉันจะศึกษาเอกสารประกอบเกี่ยวกับ API ฉบับอื่น โดยเริ่มจากบทนำและเพิ่มการตรวจสอบสิทธิ์สำหรับ API ดังกล่าว
สัปดาห์ที่ 3-8
ฉันจะเพิ่มเส้นทางและการตอบกลับของ API พร้อมด้วยตัวอย่างโค้ดสำหรับ API แต่ละประเภท (อาจมี API ประเภทที่คล้ายกัน)
สัปดาห์ที่ 9 และ 10
เพิ่มเอกสารประกอบเกี่ยวกับ API ที่จัดโครงสร้างด้วยการใช้ลิงก์ เช่น ดัชนีที่เชื่อมโยงสำหรับเอกสาร API แบบยาว และแบ่งหัวข้อเพิ่มเติมเพื่อทำอย่างอื่น เช่น ส่วนของโค้ด ภาพรวม พารามิเตอร์ และปลายทางราก
สัปดาห์สุดท้าย
ฉันจะใช้เวลาในสัปดาห์สุดท้ายในการเตรียมรายงานฉบับสุดท้ายเกี่ยวกับงานที่ทำเสร็จในระหว่างระยะเวลาการยื่นเอกสารประกอบ 12 สัปดาห์ของฉัน นอกจากนี้เราจะใช้เวลาในการตรวจสอบและสรุปเอกสารให้เสร็จสิ้น