OpenMRS 專案

本頁面包含 Google 文件季度計畫接受的技術寫作專案詳細資料。

專案摘要

開放原始碼組織：
OpenMRS
技術撰稿人：
Saurabh
專案名稱：
擴充 REST API 的 GitHub 說明文件，讓使用者更容易理解
專案長度：
標準長度 (3 個月)

Project description

主要目標

強化以 OpenMRS Swagger 為基礎的 REST API 說明文件，加入 API 的使用指南。

專案說明

OpenMRS REST API 是開發人員存取 OpenMRS 資料的重要機制之一。我們已經針對 OpenMRS Webservices API 提供以 Swagger 為基礎的自動產生文件，以及以 GitHub 為基礎的靜態文件，因此我們會在這個文件季度擴充以 GitHub 為基礎的文件。

簡要總覽

根據 Burke 的建議，我稍微研究了 OpenMRS Talk，發現這個專案早在 2017 年就以 GSOC 專案的形式開始運作。在 Gayan Weerakutti 的協助下，我們的主要目標是改善 OpenMRS REST API 的現有文件，方法是改善 Swagger 規範，並改善 Swagger 規範的產生方式，以便產生更優質的 Swagger 文件。這篇 OpenMRS 談話貼文總結了專案中完成的所有相關細節，非常實用。

隨後在 2019 年改革這項專案，改由 Swagger 文件製作不同版本。我們改為開發了一份靜態的 GitHub 友善說明文件，並將在本季的說明文件中擴充說明。

我打算說明目前的專案提案，簡單來說是：

  1. 提供一些熱門語言的範例 (特別提及 Java 和 JavaScript)。
  2. 新增板岩文件的遊樂場支援功能，就像 Swagger 的「試用」功能一樣。
  3. 重構並改善目前完成的工作。
  4. 找出並新增缺少的資源。
  5. 在文件的「控制台」部分加入更多說明

詳細說明

  1. 發想不同語言的例子。

建議您在 Java 中新增以 SDK 為基礎的範例，然後在說明文件中新增 Retrofit 範例。我認為在說明文件中加入類似 Retrofit 的例子，因為在開發 OpenMRS Android 用戶端時，加入這些 REST API 並沒有什麼實質幫助，因為我在開啟 OpenMRS Android 用戶端時，曾使用這些 REST API，而且每次需要一些資源來協助使用 Android 端點時，都無法查詢任何資源。我曾在 Android 用戶端中調整 OpenMRS API 端點，因此可以認真製作一些優質範例。我會與導師討論這個問題，並按照決定的結果進行。 此外，除了新增支援的作業範例之外，我們也應新增範例，以以部分程式設計語言使用 OpenMRS 伺服器驗證。目前我們只有 curl 範例。

  1. 新增 Playground 支援功能，以便測試 API 範例

我在在示範伺服器上代管的 OpenMRS Swagger 說明文件中使用了這項功能，這是任何 API 說明文件中非常方便使用的工具。我稍微做了一些研究，發現將 Swagger-UI 規格嵌入目前的靜態文件並不難。使用顯示/隱藏切換鈕，並使用我們目前的 Swagger 說明文件程式碼。這樣一來，我們就能確保試用功能會持續與目前的 API 規格保持一致，這也是我們將 Playground 功能整合至目前靜態文件的一種方式。

  1. 重構及改善工作方式到目前為止
檢查目前的 curl 範例

本節是今年這項專案的主要重點之一。目前，GitHub API 說明文件中只有 curl 範例，其中有些無法直接在示範伺服器上執行，因此無法直接透過瀏覽器查看。我會測試所有目前的端點，並維護一份簡單的文件，其中包含執行這些 curl 要求時取得的各種 curl 範例回應。我會使用 Postman 和 Swagger 說明文件內建的試用功能，在必要時完成這項工作。

部分範例缺少 API 回應

我們已為現有的 curl 範例新增部分回應，但部分 curl 範例沒有回應。我認為，即使回應內容不冗長 (這通常是資源清除等作業的情況)，我們也應提供 JSON API 回應範例，雖然我們已記錄所有可能的回應代碼和取得這些代碼的原因，但我認為這麼做可讓 API 說明文件中的範例更一致！

缺少各種作業的實際範例

我認為這是在重構 API 說明文件中先前完成的工作時最重要的部分，說明文件中提供可直接透過 cURL 執行的具體範例，但其中有些範例有點抽象，雖然對經驗豐富的開發人員來說是很好的參考資料，但會讓新手感到困擾。從 OpenMRS 討論串的這篇文章中，我瞭解到優質範例的價值無可取代，因此除了新增範例，我們還可以支援語法醒目顯示功能，這項功能其實不太費工，而且在 Slate 中也已內建，因此我認為這項功能很容易實作。

burke 多次強調，在文章中強調了簡潔性和描述性性，而不是優良的使用者介面，而我必須遵循這些原則，並試著與目前正在使用 OpenMRS Webservices API 的開發人員溝通，盡量讓先前記錄的端點盡量描述明確，如同我先前在討論文章中收集資源類型說明的例子。我一定會優先處理重要事務、與導師討論，並判斷哪些事項確實能為文件帶來價值，需要先完成哪些工作。

將「用途」新增為明確的標題

我看過許多 API 說明文件，只是為了熟悉這些文件，發現所有說明文件都將用途列為明確的標題，雖然我們確實有用途，但這些用途並未明確顯示，而是與資源和子資源定義後的定義和範例混在一起，因此我認為我們應該努力將用途做為獨立實體，在說明文件中加以區隔，這樣開發人員就不必透過定義推測用途，而是可以直接查詢用途。

  1. 尋找並記錄遺漏的資源

    目前的專案狀態會列出這裡的資源，但在查看這裡的最新版 Swagger 說明文件後，我發現許多資源可新增至 GitHub 友善 API 說明文件的現有資源套件，並在說明中加入其他資源，就像在 2019 年說明文件季所做的那樣。我會討論需要新增至文件的議題，並適當地加入這些內容。

結論

我已經加入 OpenMRS 社群一段時間了。我是 Android 用戶端專案的積極貢獻者，經常與 API 互動，以便與伺服器互動。因此，我認為自己很適合參與這項擴充 API 說明文件的專案，因為我可以以開發人員的角度檢視自己的工作，並評估是否確實能讓其他開發人員的工作更輕鬆。我已熟悉這個平台上用於建構這項易於使用說明文件的工具，也已為這個存放區做出多項貢獻，以便熟悉存放區和工具 (例如 slateUI)。由於 API 的優劣取決於說明文件，因此我很樂意透過改善說明文件，讓 OpenMRS Rest API 更上一層樓。

我一定會每週透過一篇座談會說明課程進度，有助於收集社群意見，並與導師和社群密切相關，充分善用這段期間的說明文件。