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 提供的密钥和值，以及该部分中密钥对应的被接受的值类型。使用任何编程语言的代码示例都有助于并明确如何在 API 中编写标头和响应格式以及其他查询参数。

  3. 其中提到了 API 提取的响应类型、JSON 类型或 API 返回的任何其他类型的结果。

  4. 不同的 API 路由以及需要随参数一起发送的所有参数、标头和其他内容。每个 API 都会借助几种语言的代码示例来协助处理，这些代码示例说明了在编写 API 代码时请求是如何产生的，除此之外，还应提及每个 API 可能会遇到的一般错误代码。

这是为 REST API 定义文档的方法的一般概念。

该项目的时间表如下：

8 月 1 日 - 9 月 1 日

与我的导师见面，更深入地讨论代码库不同部分所需的文档级别，并讨论如何深入探索低阶文档与高阶文档。我还会花时间了解代码库并学习相关概念，以便更好地记录这些概念。

第 1 周和第 2 周

我将更新并扩展贡献者指南。我会完善有关如何构建源代码的文档。此外，我还将添加“文档制作者”部分，介绍新贡献者可以在文档方面如何提供帮助。我会研究不同的 API 文档，先从介绍部分开始，并为 API 添加身份验证。

第 3 - 8 周

我会添加 API 路由和响应，以及每种 API 的一些代码示例（可能存在类型相似的 API）。

第 9 和第 10 周

添加使用链接（即针对长 API 文档的链接索引）进行结构化的 API 文档，并根据不同的依据（例如代码部分、概览、参数、根端点）进一步对其进行划分。

上周

我将在最后一周的时间里准备一份最终报告，报告在 12 周的记录期内完成的工作。我还会花时间查看并最终确定文档。