Dự án OpenMRS

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 Google 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:
Saurabh
Tên dự án:
Mở rộng Tài liệu trên GitHub về tính thân thiện với người dùng cho API REST
Thời lượng dự án:
Thời gian 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ày.

Nội dung mô tả dự án

OpenMRS REST API 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ó một tài liệu được tạo tự động dựa trên Swagger về OpenMRS Webservices API và một tài liệu tĩnh dựa trên GitHub, chúng tôi dự định sẽ 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Ề SƠ LƯỢC

Sau một thời gian tìm hiểu về OpenMRS Talk như Burke đề xuất, tôi 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à cải tiến 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 swagger. Tất cả chi tiết có liên quan được thực hiện trong dự án được tóm tắt tại đây trong bài đăng thảo luận OpenMRS này. Những chi tiết này 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 từ tài liệu của Swagger thành các chỉnh sửa tạo ra các biến thể cho dự án này. Thay vào đó, chúng tôi đã phát triển một tài liệu tĩnh thân thiện với GitHub mà chúng tôi sẽ mở rộng trong phần Tài liệu này.

Tóm tắt đề xuất dự án hiện tại mà tôi dự định mô tả là :

  1. Đưa ra ví dụ bằng một số ngôn ngữ phổ biến (cụ thể là java và javascript).
  2. Thêm tuỳ chọn hỗ trợ mô phỏng cho tài liệu về phương tiện chặn giống như tính năng ""try-out" của Swagger.
  3. Đang tái cấu trúc và cải thiện công việc mà bạn đã thực hiện cho đến nay.
  4. Tìm và thêm các tài nguyên còn thiếu.
  5. 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

  1. Đưa ra ví dụ bằng nhiều ngôn ngữ.

Bạn nên thêm các ví dụ bằng Java (dựa trên SDK), sau đó thêm các ví dụ về Retrofit mà tôi nghĩ sẽ giúp tài liệu của chúng tôi chi tiết 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 bằng 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 OpenMRS Android Client và không có tài nguyên nào để tra cứu bất cứ khi nào tôi cần trợ giúp bằng cách sử dụng các điểm cuối dành riêng cho Android. Do đã có kinh nghiệm xử lý các điểm cuối API OpenMRS trong ứng dụng Android, tôi đã nghiêm túc thực hiện được một số ví dụ chất lượng cao. Tôi sẽ thảo luận vấn đề này với các cố vấn của mình và cân nhắc quyết định. Ngoài ra, ngoài việc thêm ví dụ cho các hoạt động được hỗ trợ, chúng ta cũng nên thêm các ví dụ về cách 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ụ về curl cho trường hợp này.

  1. Thêm tính năng hỗ trợ Playground cho các ví dụ về API kiểm thử

Tôi đã sử dụng tính năng này trong tài liệu về sự phong phú 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 cần có trong mọi tài liệu về API. Tôi đã nghiên cứu một chút ở đây và không khó để nhúng thông số Swagger-UI vào tài liệu tĩnh hiện tại. Sử dụng nút bật/tắt tính năng hiển thị ẩn và sử dụng mã tài liệu thể hiện sự 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. 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.

  1. Tái cấu trúc và cải thiện công việc mà bạn đã thực hiện cho đến nay
Tham khảo các ví dụ hiện tại về curl

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ó một số ví dụ về curl có trong tài liệu về 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 qua trình duyệt. Tôi sẽ kiểm thử 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 ví dụ curl mà 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 thử nghiệm tích hợp sẵn trong tài liệu về swagger để hoàn thành nhiệm vụ này nếu cần.

Thiếu phản hồi API trên một số ví dụ

Một số phản hồi đã được thêm vào cho các ví dụ về 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á tài nguyên, chúng ta nên có một Phản hồi API JSON mẫu 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 để có được chúng. Tôi nghĩ đ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 hoạt động đối với nhiều thao tác khác nhau

Tôi nghĩ đây sẽ là phần quan trọng nhất của 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. Tài liệu 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ụ hơi trừu tượng nên tham khảo tốt đến các nhà phát triển có kinh nghiệm nhưng lại khiến những người mới tham gia trong trạng thái lo ngại. 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 thực sự không có nhiều công việc, nó đi kèm với phương tiện chặn, giúp việc này khá dễ thực hiện như tôi đã tìm hiểu ở đây,

Vì burke đã nhiều lần nhấn mạnh trong bài đăng của mình, ưu tiên sự đơn giản và tính mô tả trong tài liệu thay vì giao diện 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 về OpenMRS Webservices API và tương tác với cộng đồng, giống như trong bài đăng thảo luận về việc thu thập mô tả cho các loại thuộc tính cho các tài nguyên biểu mẫu mà tôi không rõ ở đây. Tôi thực sự sẽ nỗ lực giải quyết những việc cần ưu tiên, trao đổi với người cố vấn để quyết định xem đâu là những nội dung thực sự tạo ra giá trị cho tài liệu và cần phải 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 về API chỉ để giải thích và thấy rằng tất cả các tài liệu này đề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 mà chúng không hiển thị rõ ràng, chúng được kết hợp một phần trong các định nghĩa và ví dụ theo sau định nghĩa của tài nguyên và tài nguyên phụ.

  1. Tìm và ghi lại các tài nguyên còn thiếu

    Trạng thái hiện tại của dự án 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ự phong phú tại đâ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 về API thân thiện với GitHub với phần mô tả như đã hoàn thành với các tài nguyên khác trong Phần Tài liệu năm 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 cho 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 máy chủ. Do đó, tôi cảm thấy mình có thể thực hiện 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 công cụ này có thực sự giúp giảm bớt công việc của các nhà phát triển khác hay không.

Tôi đảm bảo sẽ thông báo về tiến độ hằng tuần bằng một bài đăng thảo luậ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.