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 合作，Gayan Weerakutti 的主要目標是改善 OpenMRS REST API 的現有說明文件，同時改善 Swagger 規格，並改進 Swagger 規格的產生方式，進而產生更好的 swagger 說明文件。這份 OpenMRS 演講文章匯總了這項專案中完成的所有相關資訊，非常實用。

隨後在 2019 年，我們翻新了這項專案，接著停止在 Swagger 說明文件中做出一些變化版本。相反地，我們開發了一份易於使用的靜態 GitHub 文件，預計會延伸到這一季的 Google 文件。

所以我想簡單介紹目前的專案提案：

  1. 並提供一些熱門程式語言的範例 (特別提及 Java 和 JavaScript)。
  2. 針對插入畫面說明文件新增 Playground 支援，就像 Swagger「try-out」功能一樣。
  3. 在此之前重構及改善工作。
  4. 尋找及新增缺少的資源。
  5. 在文件的控制台部分中提供更多說明

詳細說明

  1. 這裡提供不同語言的範例。

建議您新增以 SDK 為基礎的 Java 範例，然後加入 Retrofit 範例，我們認為該範例會增加說明文件深度。這是因為在 OpenMRS Android 用戶端工作時，我曾使用這些 REST API，對新增 retrofit 範例的一種語言助益更有效。而且由於我在 OpenMRS Android 用戶端使用了這些 REST API，而且完全沒有資源專用的端點，需要針對 Android 專用的端點提供協助嗎？有鑑於我在 Android 用戶端中使用 OpenMRS API 端點的經驗，我能認真製作一些優質範例。 我會與導師討論此情況，並共同決定最終結果。 除了新增支援作業的範例外，在部分程式設計語言中，我們也會加入透過 OpenMRS 伺服器進行驗證的範例。我們目前只提供 curl 範例。

  1. 新增 Playground 支援以測試 API 範例

我已在示範伺服器代管的 OpenMRS 說明文件中使用這項功能。也就是說，在所有 API 說明文件中，這是相當方便的工具。 我在這裡研究了點子，想將 Swagger-UI 規格嵌入目前的靜態說明文件中並不容易。使用「Show Hide」切換鈕，以及使用我們現有的便捷說明文件程式碼。如此一來，我們甚至可以確保試用功能依目前的 API 規格運作，這是讓我將模擬功能功能整合至目前的靜態文件的方法之一。

  1. 重構及改善工作成果
檢查目前的 curl 範例

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

部分範例缺少 API 回應

現有 curl 範例已新增部分回應，但部分 curl 範例沒有回應。 我認為即使回應並不複雜，例如清除資源等作業，我們還是應該提供 JSON API 回應範例。不過，我們已經記錄了所有可能的回應代碼，而且說這些回應的原因會讓 API 說明文件中的樣本更有一致！

各項作業缺少工作範例

我認為這是重構 API 說明文件中之前完成工作的關鍵部分，說明文件中提供了具體範例，可直接使用 cURL 執行，但其中有些是比較抽象的，可為經驗豐富的開發人員提供良好的參考資料，但讓新手陷入困境。 我從 OpenMRS 的本文中學到，優質範例是無價的例子，除了加入一些範例，我們還能支援使用語法醒目顯示功能。這其實並不多。

Buke 多次強調文件中的簡單性和描述性，因此取代良好的使用者介面和閃光介面，因此我遵守這些原則，盡可能與目前正在使用 OpenMRS Webservices API 的開發人員交流，並盡量與社群互動，就像我在 PR 中對於屬性類型明確說明的 PR 資源說明一樣。 我真正的工作是優先處理優先事項，與導師討論，決定哪些事情對文件有很大的幫助，需要優先完成。

將用途新增為明確的標題

我看過許多 API 說明文件只是用來掌握這些概念，並發現所有 API 說明文件都是明確的標題。雖然我們確實有用途未明確顯示，但在資源和子資源定義後，這些用途就有些微妙。 我認為在定義使用案例後，應該設法將用途區分為獨立的實體，這樣開發人員才不會真正想在文件中使用用途，而在搜尋使用案例中，想把用途區分為獨立的實體。

  1. 尋找及記錄缺少的資源

    這裡列出了目前專案狀態的資源，不過在這裡可以看見最新版本的文件，我可以在適用於 GitHub 的 API 文件的現有資源套件中加入許多資源，並在 2019 年文件季期間提供其他資源的說明。我會討論需要加入文件的主題，並適當新增。

結論

我參與了 OpenMRS 社群已有一段時間，我是 Android 用戶端專案的有效貢獻者，我會在此專案經常與伺服器互動的 API 互動。因此，我覺得自己可以輕鬆擴充 API 文件，因為我可以自己看著自己的開發人員，並評估它是否可有效改善其他開發人員的處理工作。我也已經熟悉適合用於此處代管說明文件存放區的工具，也對這個存放區做出了幾項改善，為了熟悉這個存放區和工具，我也很喜歡 ReMRS API。

我每週都會透過口語貼文向社群傳達進度，並協助收集社群成員的意見回饋，並與我的導師和社群密切相關，以便充分運用這段說明文件。