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 Google Phần Tài liệu.
Tóm tắt dự án
- Tổ chức nguồn mở:
- OpenMRS
- Người viết nội dung kỹ thuật:
- Ả Rập Xê Út
- Tên dự án:
- Mở rộng Tài liệu về tính thân thiện với người dùng trên GitHub cho API REST
- Thời lượng dự án:
- Thời lượng tiêu chuẩn (3 tháng)
Mô tả dự án
Mục tiêu chính
Cải thiện tài liệu về API REST dựa trên OpenMRS Swagger để thêm hướng dẫn về việc sử dụng API.
Nội dung mô tả dự án
API OpenMRS REST là một trong những cơ chế chính để nhà phát triển truy cập vào dữ liệu từ OpenMRS. Hiện đã có tài liệu được tạo tự động dựa trên Swagger về API OpenMRS Webservices và tài liệu tĩnh dựa trên GitHub. Chúng tôi dự định mở rộng tài liệu dựa trên GitHub đó trong Phần Tài liệu này.
TỔNG QUAN VỀ TÓM TẮT
Sau khi tìm hiểu một chút về OpenMRS Talk theo gợi ý của Burke, tôi được biết rằng dự án này bắt đầu từ năm 2017 dưới dạng một dự án GSOC. Với Gayan Weerakutti, mục tiêu chính là cải thiện tài liệu hiện có về API OpenMRS REST, bằng cách cải thiện Thông số kỹ thuật Swagger và thông qua các cải tiến về cách tạo Thông số kỹ thuật Swagger để tạo ra phiên bản tốt hơn của tài liệu về sự hào hứng. Tất cả chi tiết có liên quan đã đạt được trong dự án đã được tóm tắt tại đây trong bài nói chuyện trên OpenMRS và khá hữu ích.
Sau đó, vào năm 2019, dự án này được cải tiến và chúng tôi chuyển sang điều chỉnh tài liệu của Swagger để tạo ra các biến thể cho chủ đề này. Thay vào đó, chúng tôi đã phát triển một tài liệu tĩnh dành cho GitHub mà chúng tôi sẽ mở rộng trong phần Tài liệu này.
Tóm lại đề xuất dự án hiện tại mà tôi định mô tả là :
- Đưa ra ví dụ bằng một số ngôn ngữ phổ biến (cụ thể là JavaScript và JavaScript).
- Thêm tuỳ chọn hỗ trợ Playground cho tài liệu về phương tiện chặn giống như tính năng ""try-out" của Swagger.
- Tái cấu trúc và cải thiện công việc đã hoàn thành cho đến bây giờ.
- Tìm và thêm tài nguyên bị thiếu.
- Thêm nội dung mô tả khác vào phần bảng điều khiển của tài liệu
MÔ TẢ CHI TIẾT
- Đưa ra ví dụ bằng nhiều ngôn ngữ.
Bạn nên thêm các ví dụ trong Java (dựa trên SDK), sau đó thêm các ví dụ Retrofit mà tôi cho rằng sẽ giúp tài liệu của chúng ta chuyên sâu hơn, vì việc thêm ví dụ bằng một ngôn ngữ khác như JavaScript sẽ không hữu ích nhiều như việc thêm các ví dụ về Retrofit vì tôi đã sử dụng các API REST này trong khi làm việc trên Ứng dụng Android OpenMRS và không có tài nguyên nào để tra cứu mỗi khi tôi cần trợ giúp về điểm cuối dành riêng cho Android. Và tôi có thể nghiêm túc đưa ra một số ví dụ chất lượng cao ở đây, với kinh nghiệm của tôi khi sử dụng các điểm cuối của OpenMRS API trong ứng dụng Android. Tôi sẽ thảo luận về vấn đề này với những người cố vấn của mình và tìm ra quyết định. Ngoài ra, ngoài việc thêm ví dụ về các hoạt động được hỗ trợ, chúng tôi cũng nên thêm các ví dụ để xác thực với máy chủ OpenMRS bằng một số ngôn ngữ lập trình. Hiện tại, chúng tôi chỉ có các ví dụ curl cho trường hợp này.
- Thêm tính năng hỗ trợ Playground cho ví dụ về API kiểm thử
Tôi đã sử dụng tính năng này trong tài liệu về hồ sơ của OpenMRS được lưu trữ tại máy chủ minh hoạ và đây là một công cụ thực sự tiện lợi trong bất kỳ tài liệu API nào. Tôi đã nghiên cứu một chút ở đây và không khó để nhúng thông số kỹ thuật của Swagger-UI vào tài liệu tĩnh hiện tại. Sử dụng nút bật/tắt hiển thị ẩn và sử dụng mã tài liệu phong phú hiện tại mà chúng ta có. Bằng cách này, chúng ta thậm chí có thể đảm bảo rằng tính năng dùng thử vẫn hoạt động với các thông số kỹ thuật hiện tại của API. Đây là một cách tôi tin rằng chúng ta có thể tích hợp các tính năng mô phỏng vào tài liệu tĩnh hiện tại của mình.
- Tái cấu trúc và cải thiện công việc đã thực hiện cho đến bây giờ
Đang kiểm tra các ví dụ về curl hiện tại
Phần này là một trong những điểm nhấn chính của dự án này trong năm nay. Hiện tại, chỉ có các ví dụ về curl có trong các tài liệu API GitHub, một số ví dụ không thể chạy trực tiếp trên máy chủ minh hoạ để kiểm tra trực tiếp từ trình duyệt. Tôi sẽ thử nghiệm tất cả các điểm cuối hiện tại và duy trì một tài liệu đơn giản với nhiều phản hồi của các ví dụ curl chúng tôi nhận được khi chạy các yêu cầu curl đó. Tôi sẽ sử dụng Postman cùng với tính năng dùng thử tích hợp trong tài liệu về tính năng swagger để hoàn thành nhiệm vụ này nếu cần.
Thiếu phản hồi của API trong một số ví dụ
Một số phản hồi đã được thêm cho các ví dụ curl hiện tại, nhưng một số ví dụ về curl không có phản hồi. Tôi nghĩ ngay cả khi phản hồi không chi tiết, thường xảy ra với các hoạt động như xoá hoàn toàn tài nguyên, chúng ta vẫn nên có một ví dụ về Phản hồi API JSON mặc dù chúng tôi đã ghi lại tất cả các mã phản hồi có thể có và lý do để khiến chúng tôi nghĩ rằng điều này sẽ làm cho các ví dụ trên tài liệu API thống nhất hơn !!
Thiếu ví dụ về cách thực hiện trên nhiều phép toán
Tôi cho rằng đây sẽ là phần quan trọng nhất trong việc tái cấu trúc công việc đã hoàn thành trước đó trong tài liệu về API, có một số ví dụ cụ thể trong tài liệu có thể được thực thi trực tiếp bằng cURL, nhưng một số ví dụ trong số đó chỉ mang tính trừu tượng một chút tham khảo tốt cho các nhà phát triển có kinh nghiệm nhưng lại khiến những người mới đến cảm thấy bận tâm. Như tôi có thể thu thập được từ bài đăng này trong OpenMRS nói rằng các ví dụ hay là vô giá, vì vậy, ngoài việc thêm ví dụ về công việc, chúng tôi có thể hỗ trợ đánh dấu cú pháp mà thực sự không có nhiều công việc, nó còn đi kèm với phương tiện chặn giúp điều này khá dễ thực hiện như tôi đã tìm ra ở đây,
Vì burke đã nhấn mạnh nhiều lần trong bài đăng của mình rằng ưu tiên sự đơn giản và mô tả trong tài liệu thay vì giao diện người dùng tốt và giao diện sáng bóng, tôi sẽ tuân thủ các nguyên tắc này và cố gắng làm cho các điểm cuối được ghi lại trước đây trở nên mô tả nhất có thể bằng cách trò chuyện với các nhà phát triển hiện đang làm việc trên OpenMRS Webservices API và tương tác với cộng đồng, giống như tôi đã làm trong bài đăng để thu thập mô tả cho các loại thuộc tính cho tài nguyên biểu mẫu mà tôi không hiểu rõ ở đây. Tôi sẽ thực sự giải quyết những việc cần ưu tiên, trao đổi với người cố vấn của mình và quyết định những điều thực sự bổ sung giá trị cho tài liệu và cần được hoàn thành trước tiên.
Thêm các trường hợp sử dụng làm dòng tiêu đề rõ ràng
Tôi đã xem nhiều tài liệu API chỉ để tìm hiểu và thấy rằng tất cả chúng đều có các trường hợp sử dụng dưới dạng tiêu đề rõ ràng, mặc dù chúng tôi có các trường hợp sử dụng không hiển thị rõ ràng, chúng được kết hợp một phần bên trong định nghĩa và ví dụ theo sau phần định nghĩa của tài nguyên và tài nguyên phụ. Tôi cho rằng chúng ta nên cố gắng phân tách Các trường hợp sử dụng thành một thực thể riêng biệt trong tài liệu để nhà phát triển không thực sự phải tìm kiếm qua các trường hợp thay vì tìm kiếm qua các định nghĩa nữa.
Tìm và ghi lại các tài nguyên còn thiếu
Trạng thái dự án hiện tại có các tài nguyên được liệt kê ở đây, nhưng khi xem phiên bản mới nhất của tài liệu về sự vênh vang ở đây, tôi có thể tìm ra nhiều tài nguyên có thể được thêm vào bộ tài nguyên hiện tại trong các tài liệu API thân thiện với GitHub với mô tả như đã hoàn thành với các tài nguyên khác trong Mùa Tài liệu 2019. Tôi sẽ thảo luận những chủ đề cần bổ sung vào tài liệu và bổ sung cho phù hợp.
KẾT LUẬN
Tôi đã tham gia cộng đồng OpenMRS được một thời gian. Tôi là người đóng góp tích cực vào dự án Android Client, nơi tôi thường xuyên tương tác với các API để tương tác với các máy chủ. Do đó, tôi cảm thấy mình có thể hoàn thành dự án mở rộng tài liệu API này khá tốt vì tôi có thể tự mình xem công việc của mình với tư cách là một nhà phát triển và đánh giá xem nó có thực sự dễ dàng công việc của các nhà phát triển khác hay không. Tôi đã làm quen với các công cụ được sử dụng cho kho lưu trữ tài liệu thân thiện với người dùng được lưu trữ ở đây.
Tôi đảm bảo sẽ thông báo về tiến độ học tập hằng tuần qua một bài đăng trò chuyện. Việc này sẽ giúp thu thập ý kiến phản hồi của cộng đồng và phối hợp chặt chẽ với người cố vấn cũng như cộng đồng của mình để khai thác tối đa giai đoạn tài liệu này.