OpenMRS 專案

本頁詳細說明 Google 文件季度接受的一項技術撰寫專案詳細資料。

專案摘要

開放原始碼組織：
OpenMRS
技術撰稿人：
Saurabh
專案名稱：
為 REST API 延長使用者友善的 GitHub 說明文件
專案長度：
標準長度 (3 個月)

Project description

主要目標

強化以 OpenMRS Swagger 為基礎的 REST API 說明文件，新增 API 使用指引。

專案說明

OpenMRS REST API 是開發人員存取 OpenMRS 資料時的主要機制之一。已有由 Swagger 自動產生的 OpenMRS Webservices API 說明文件，以及以靜態 GitHub 為基礎的說明文件，我們應該在本季的「文件」季中擴充該 GitHub 的說明文件。

概要總覽

如同 Burke 所建議的 OpenMRS Talk 研究，我得知這項專案是從 2017 年開始以 GSOC 專案的形式開始運作。Gayan Weerakutti 主要目標是改善 OpenMRS REST API 的現有說明文件，具體做法包括改善 Swagger 規範及改進 Swagger 規範的產生方式，進而產生更好的 Swagger 文件版本。這份 OpenMRS 講座貼文總結了這項專案中完成的所有相關細節，非常實用。

隨後在 2019 年，這項專案經過重整，隨後從 Swagger 的說明文件中，我們調整了產生不同之處。取而代之的是，我們開發出適用於 GitHub 的靜態說明文件，預計在本季延伸文件。

我想簡單說明目前的專案提案：

  1. 提供一些常用程式語言的範例 (特別是 Java 和 JavaScript)。
  2. 為插入畫面說明文件新增遊樂場支援，就像 Swagger 的「try-out」功能一樣。
  3. 到目前為止，完成重構並改善作業。
  4. 找出並新增缺少的資源。
  5. 在文件的控制台部分加入更多說明

詳細說明

  1. 建立不同語言的例子。

我建議在 Java 中新增以 SDK 為基礎的範例，然後新增 retrofit 範例，相信這會在說明文件中增加深度。由於我曾在使用 OpenMRS Android 用戶端時使用這些 REST API，因此新增 Retrofit 範例不太容易，而且在需要有關 Android 端點的專用端點協助時，也沒有需要尋找的資源。鑒於我與 Android 用戶端中的 OpenMRS API 端點經驗，我就能實際製作一些優質範例。 我會和導師討論這個部分，一起決定決定的方向。 除了為支援的作業新增範例之外，我們也應新增一些程式設計語言，以使用 OpenMRS 伺服器進行驗證的範例。我們目前只提供 curl 範例。

  1. 為測試 API 範例新增 Playground 支援功能

我已在示範伺服器代管 OpenMRS 的 Swagger 說明文件中使用這項功能，在任何 API 說明文件中，這項功能相當便利。我在這裡稍微研究了一下，將 Swagger-UI 規格嵌入目前的靜態說明文件並不容易。使用顯示隱藏切換按鈕，並使用我們提供的現有 Swagger 說明文件程式碼。如此一來，我們甚至可以確保試用功能仍維持在目前的 API 規格。我們相信可以透過此方法將 Playground 功能整合至目前的靜態說明文件中。

  1. 到目前為止完成重構並改善作業
檢查目前的 curl 範例

本節是本專案今年的主要重點之一，目前 GitHub API 文件只提供 curl 範例，其中有些無法直接在示範伺服器上執行，無法直接從瀏覽器檢查。我會測試目前的所有端點，並維護一份簡單的文件，內含執行這些 curl 要求時所收到的各種 curl 範例回應。除了 Swagger 說明文件內建的試用功能外，我還會使用 Postman 來完成這項工作。

部分示例缺少 API 回應

我們已為目前的 curl 範例新增部分回應，但部分 curl 範例沒有回應。我覺得即使回應不是繁雜，例如清除資源等作業的情況，我們應該提供 JSON API 回應範例，但我們已經將所有可能的回應代碼記錄下來，也說明瞭這麼做可讓 API 說明文件中的範例更加統一！！

缺少多項作業的應用範例

在 API 說明文件中，這將是重構先前完成的工作最重要的部分，說明文件中提供了具體範例，可直接使用 cURL 執行。不過其中有些範例雖然簡略，有助於經驗老手的需要參考，同時讓新進員工處於異同狀態。 我可以在 OpenMRS 的這篇文章中，獲得優質範例是無價的，因此除了新增工作範例外，我們也能支援語法醒目顯示功能。事實上，這確實是搭配插入畫面使用，這非常容易達成上述目標。

由於 burke 多次強調，比起文件中的簡單明瞭的使用者介面和簡潔的介面，Bburke 多次強調，我會遵循這些原則，並盡量與目前正在使用 OpenMRS Webservices API 的開發人員溝通，並鼓勵他們與社群互動，把先前記錄的端點設計成敘述性。我應該優先處理事情，先和導師討論，並決定哪些事項對文件真正有附加價值，而且需要先達成。

新增用途做為明確標題

我看過許多 API 說明文件，用來瞭解它們的運作原理，並發現所有用途都是明確的標題，但有些用途並未明確地融入了定義和範例，在資源和子資源的定義之後，我們應該設法將「用途」分隔為獨立實體，而不是在說明文件中將用途區隔為獨立實體，這樣開發人員才不會真正找出相關用途。

  1. 找出並記錄缺少的資源

    這裡列出了目前的專案狀態資源，但在這裡可以看到最新版 Swagger 說明文件，我不妨找出許多資源，這些資源可以新增至 GitHub 相容 API 文件的現有資源套件中，並附有參考「2019 年文件」季中其他資源的說明。 我會討論需要加入文件的主題，然後視情況加入這些主題。

結論

我是 OpenMRS 社群的一員，我是 Android 用戶端專案的主動貢獻者，在當中經常與 API 互動。因此，我覺得 API 文件延伸功能很好，因為我自己就是開發人員，負責評估我的工作成果，評估是否能協助其他開發人員處理工作，並且已經熟悉這裡所代管說明文件存放區所使用的工具，因此我也對這個存放區做出了幾項貢獻，以便熟悉存放區和工具。這樣，讓 API 文件更臻完善。

我每週都會發布說明貼文來掌握社群進度，並且與導師和社群密切相關，以便充分運用這段期間的說明文件。