Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần tài liệu của Google.
Tóm tắt dự án
- Tổ chức nguồn mở:
- OpenMRS.org
- Người viết nội dung kỹ thuật:
- batbrain7
- Tên dự án:
- Tài liệu về API REST OpenMRS
- Độ dài dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Tôi sẽ chia đề xuất của mình thành nhiều phần và sẽ tuân theo quy trình như tài liệu về API Google Maps và tài liệu về API GitHub.
Ngoài ra, tôi cũng muốn đề xuất cấu trúc readme cho tài liệu API do thực tế.io thực hiện: https://github.com/gothinkster/realworld/tree/master/api
Cá nhân tôi thấy tài liệu này rất dễ hiểu và dễ sử dụng.
Đề xuất của tôi chủ yếu bao gồm 3 phần :
Một phần giới thiệu nhanh về API, về OpenMRS và cách sử dụng API này cũng như những điều sau đó.
Cách lấy khoá API và thông tin xác thực cần thiết nói chung để tạo yêu cầu API. Phần này sẽ bao gồm một ví dụ mẫu về các loại xác thực có trong API cũng như các khoá và giá trị cần có trong API, cũng như các loại giá trị được chấp nhận tương ứng với khoá trong phần đó. Mẫu mã bằng bất kỳ ngôn ngữ nào cũng sẽ hỗ trợ và làm rõ cách viết tiêu đề, định dạng phản hồi và các tham số truy vấn khác trong API.
Bạn cần đề cập đến các loại phản hồi mà API tìm nạp, các loại JSON hoặc bất kỳ loại kết quả nào khác mà API trả về.
Các tuyến API khác nhau và tất cả các tham số cần được gửi cùng với các tuyến đó, tiêu đề và các nội dung khác. Mỗi API sẽ được hỗ trợ bằng mã mẫu bằng một vài ngôn ngữ mô tả cách thực hiện yêu cầu trong khi viết mã cho API đó, ngoài các mã lỗi chung có thể gặp phải với mỗi API, bạn cũng nên đề cập đến.
Đây là ý tưởng chung về cách xác định tài liệu cho API REST.
Lịch biểu của dự án như sau :
Từ ngày 1 tháng 8 đến ngày 1 tháng 9
Làm quen với người cố vấn của tôi và thảo luận sâu hơn về cấp độ tài liệu cần thiết ở các phần khác nhau của cơ sở mã, đồng thời thảo luận về mức độ chi tiết của tài liệu cấp thấp so với tài liệu cấp cao. Tôi cũng sẽ dành thời gian này để tìm hiểu cơ sở mã và nghiên cứu các khái niệm để có thể ghi lại các khái niệm đó rõ ràng hơn.
Tuần 1 và 2
Tôi sẽ cập nhật và mở rộng hướng dẫn dành cho cộng tác viên. Tôi sẽ cải thiện tài liệu về cách tạo mã nguồn. Tôi cũng sẽ thêm một phần dành cho người viết tài liệu về cách những người đóng góp mới có thể giúp đỡ trong việc viết tài liệu. Tôi sẽ nghiên cứu các tài liệu về API khác nhau và bắt đầu bằng phần giới thiệu, sau đó thêm tính năng xác thực cho API.
Tuần 3 – 8
Tôi sẽ thêm các tuyến và phản hồi API cùng với một số mã mẫu cho từng loại API (có thể có các loại API tương tự).
Tuần 9 và 10
Thêm cấu trúc tài liệu API bằng các đường liên kết, tức là một chỉ mục được liên kết cho tài liệu API dài và chia tài liệu đó thành nhiều phần khác nhau như phần mã, thông tin tổng quan, tham số, điểm cuối gốc.
Tuần cuối cùng
Tôi sẽ dùng tuần cuối cùng để chuẩn bị báo cáo cuối cùng về những công việc mình đã làm trong khoảng thời gian 12 tuần sắp xếp tài liệu. Tôi cũng sẽ dành thời gian này để xem xét và hoàn thiện hồ sơ.