OpenMRS.org 專案

本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。

專案摘要

開放原始碼機構：
OpenMRS.org
技術文件撰寫者：
batbrain7
專案名稱：
OpenMRS REST API 說明文件
專案長度：
標準長度 (3 個月)

Project description

我會將提案分為多個部分，並按照 Google Maps API 說明文件和 GitHub API 說明文件等流程操作。

除了上述項目外，我也想提議一份 Realworld.io 的 API 說明文件讀取結構：https://github.com/gothinkster/realworld/tree/master/api

我個人認為這份說明文件非常容易理解及使用。

我的提案主要包含 3 個部分：

  1. 這個部分會簡要介紹這個 API、OpenMRS、API 的使用方式，以及後續內容。

  2. 如何取得 API 金鑰及提出 API 要求的一般必要驗證。這會包含 API 中顯示的驗證類型範例、需加入的金鑰和值，以及該部分中的鍵所接受的對應值類型。任何語言的程式碼範例都可協助並瞭解如何在 API 中撰寫標頭和回應格式和其他查詢參數。

  3. API 擷取的回應類型包括 JSON 的類型，或 API 傳回的任何其他結果類型。

  4. 不同的 API 路徑，以及所有需要傳送的參數、標頭和其他內容。每個 API 將透過幾種語言的程式碼範例協助，說明在編寫程式碼時如何提出要求 (除了各個 API 可能會遇到的一般錯誤代碼以外)。

這是關於 REST API 定義文件的一般做法。

專案的排程如下：

8 月 1 日至 9 月 1 日

熟悉我的導師，並進一步討論程式碼集不同部分所需的文件層級，並探討如何深入介紹低階和高階說明文件。我也會抽空瞭解程式碼集並研究相關概念，以便進一步記錄。

第 1 週和第 2 週

我會更新並補充貢獻者指南。我會改善有關如何建構原始碼的說明文件。我也會在說明文件中新增文件人員部分，說明新貢獻者可提供哪些協助。我將研究其他 API 說明文件，首先介紹 API 的驗證機制。

第 3 至 8 週

新增 API 路徑和回應，以及每種 API 類型的程式碼範例 (API 類型可能很類似)。

第 9 週 & 10 週

新增 API 說明文件結構，使用連結建立結構，也就是 API 說明文件已連結的索引，然後根據程式碼區段、總覽、參數、根端點等不同方式進一步分割。

最後一週

我會在 12 週的說明文件期間，利用最後一週準備最終工作報告。我也會利用這段時間檢視及完成說明文件。