OpenMRS.org 项目

本页详细介绍了 Google 文档季收录的技术文案项目。

项目摘要

开源组织：
OpenMRS.org
技术文档工程师：
batbrain7
项目名称：
OpenMRS REST API 文档
项目时长：
标准时长（3 个月）

Project description

我会将我的提案拆分为不同的部分，并遵循 Google 地图 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 周的记录期内所完成的工作，准备最终报告。我还会利用这段时间来检查并最终确定相关文档。