Dự án OpenMRS

Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.

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 GitHub thân thiện với người dùng cho API REST
Thời lượng dự án:
Thời hạn 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 Swagger của OpenMRS để thêm hướng dẫn về cách sử dụng API.

Mô tả dự án

API REST OpenMRS là một trong những cơ chế chính để nhà phát triển truy cập dữ liệu từ OpenMRS. Hiện đã có tài liệu được tạo tự động dựa trên Swagger về API Dịch vụ web OpenMRS 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 mùa Tài liệu này.

TỔNG QUAN NHANH

Sau khi tìm hiểu một chút 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ó của API OpenMRS REST, bằng cách cải thiện Thông số kỹ thuật Swagger và thông qua các điểm cải tiến về cách tạo Thông số kỹ thuật Swagger để tạo ra phiên bản tài liệu swagger tốt hơn. Tất cả chi tiết liên quan đến dự án đã được tóm tắt tại đây trong bài đăng trò chuyện OpenMRS này 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 từ việc điều chỉnh tài liệu Swagger để tạo ra các biến thể trên đó. 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 mùa Tài liệu này.

Vì vậy, tôi dự định mô tả ngắn gọn về đề xuất dự án hiện tại như sau :

  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 tính năng hỗ trợ sân chơi cho tài liệu Slate giống như tính năng ""thử nghiệm"" của Swagger.
  3. Đang tái cấu trúc và cải thiện những việc bạn đã làm cho đến nay.
  4. Tìm và thêm các tài nguyên bị thiếu.
  5. Thêm một đoạn mô tả khác vào phần bảng điều khiển của tài liệu

NỘI DUNG MÔ TẢ CHI TIẾT

  1. Tạo ví dụ bằng nhiều ngôn ngữ.

Tôi đề xuất thêm các ví dụ trong java dựa trên SDK, sau đó thêm các ví dụ về retrofit mà tôi cho là sẽ giúp tài liệu của chúng ta thêm sâu sắc hơn, vì việc thêm các 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 Ứng dụng Android OpenMRS và không có tài nguyên nào để tham khảo bất cứ khi nào tôi cần trợ giúp về việc sử dụng các điểm cuối dành riêng cho Android. Và tôi sẽ có thể nghiêm túc đưa ra một số ví dụ chất lượng ở đây dựa trên kinh nghiệm của tôi khi sử dụng các điểm cuối OpenMRS API trong ứng dụng Android. Tôi sẽ thảo luận vấn đề này với các cố vấn của mình và thực hiện theo quyết định. Ngoài ra, ngoài việc thêm ví dụ cho các thao tác được hỗ trợ, chúng ta cũng nên thêm các ví dụ về cách xác thực bằng 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 vấn đề này.

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

Tôi đã sử dụng tính năng này trong tài liệu swagger 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ó trong bất kỳ tài liệu API nào. Tôi đã nghiên cứu một chút ở đây và việc nhúng thông số kỹ thuật Swagger-UI vào tài liệu tĩnh hiện tại không quá khó. Sử dụng nút bật/tắt hiển thị/ẩn và sử dụng mã tài liệu swagger hiện 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 API hiện tại. Đây là một cách mà tôi tin rằng chúng ta có thể tích hợp các tính năng của Playground vào tài liệu tĩnh hiện tại.

  1. Tái cấu trúc và cải thiện công việc đã thực hiện cho đến thời điểm này
Kiểm tra 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ó các ví dụ về curl trên tài liệu API GitHub, một số ví dụ trong đó 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ẽ 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 các ví dụ về curl mà chúng ta 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 sẵn trong tài liệu về phong cách khoa học để thực hiện 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ĩ rằng ngay cả khi các phản hồi không chi tiết, thường là với các thao tác 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 ta đã ghi lại tất cả mã phản hồi có thể có và lý do để nhận 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 trên nhiều thao tác

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 API. Có các 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, cung cấp tài liệu tham khảo hữu ích cho các nhà phát triển giàu kinh nghiệm nhưng khiến người mới gặp khó khăn. Như tôi có thể thu thập được từ bài đăng này trong cuộc trò chuyện về OpenMRS, các ví dụ hay là vô giá. Vì vậy, ngoài việc thêm các ví dụ về công việc, chúng ta có thể hỗ trợ tính năng làm nổi bật cú pháp. Đây thực sự không phải là công việc quá lớn, nó hầu như đi kèm với slate, giúp việc này khá dễ dàng như tôi đã tìm thấy ở đây,

Như burke đã nhấn mạnh nhiều lần 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 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 nhận trước đó mô tả càng rõ ràng càng tốt 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 API dịch vụ web OpenMRS và tương tác với cộng đồng, giống như tôi đã làm trong bài đăng thảo luận để thu thập nội dung mô tả về các loại thuộc tính cho tài nguyên biểu mẫu mà tôi không rõ trong PR của mình tại đây. Tôi sẽ thực sự tập trung vào những việc ưu tiên thông minh, trao đổi với cố vấn và quyết định những điều thực sự tăng thêm giá trị cho tài liệu và cần phải hoàn thành trước tiên.

Thêm trường hợp sử dụng dưới dạng dòng tiêu đề rõ ràng

Tôi đã thấy nhiều tài liệu về API chỉ để giúp bạn nắm bắt và thấy rằng tất cả các trường hợp sử dụng này đều 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ó những trường hợp sử dụng không hiển thị rõ ràng, chúng phần nào được hợp nhất bên trong các định nghĩa và ví dụ theo sau định nghĩa về tài nguyên và tài nguyên phụ. Tôi nghĩ rằng chúng ta nên cố gắng tách riêng các Trường hợp sử dụng dưới dạng một thực thể riêng biệt trong tài liệu để nhà phát triển thực sự không phải tìm kiếm qua các trường hợp.

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

    Trạng thái dự án hiện tại có các tài nguyên được liệt kê tại đây, nhưng khi xem phiên bản mới nhất của tài liệu swagger 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 tài liệu API thân thiện với GitHub với nội dung mô tả được 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 về các chủ đề cần thêm vào tài liệu và thêm các chủ đề đó một cách phù hợp.

KẾT LUẬN

Tôi đã tham gia cộng đồng OpenMRS được một thời gian. Tôi là một cộng tác viên tích cực cho dự án Ứng dụng Android, 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ể làm việc khá tốt trong dự án mở rộng tài liệu API này vì tôi có thể tự 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 việc đó có thực sự giúp các nhà phát triển khác dễ dàng hơn hay không. Tôi đã làm quen với các công cụ 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ữ tại đây. Tôi cũng đã đóng góp một số nội dung cho kho lưu trữ này để làm quen với kho lưu trữ và các công cụ, tức là slateUI. Vì một API được cho là tốt như tài liệu của API đó, nên tôi muốn cải thiện tài liệu của OpenMRS Rest API một chút.

Tôi sẽ đảm bảo thông báo tiến trình hằng tuần bằng một bài đăng trò chuyện để nhận ý kiến phản hồi từ cộng đồng, đồng thời phối hợp chặt chẽ với người cố vấn và cộng đồng để tận dụng tối đa khoảng thời gian viết tài liệu này.