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 可能会出现的常规错误代码。

本文概述了如何为 REST API 定义文档。

该项目的时间安排如下：

8 月 1 日至 9 月 1 日

结识我的导师，更深入地讨论代码库不同部分所需的文档级别，并讨论如何深入构建低级别文档与高级文档。我还会花时间了解代码库并研究相关概念，以便更好地记录代码库。

第 1 周和第 2 周

我将更新并扩展贡献者指南。我会完善关于如何构建源代码的文档。我还将添加文档作者部分，介绍新贡献者可以如何帮助文档制作内容。我会研究不同的 API 文档，先从简介开始，并为 API 添加身份验证。

第 3 - 8 周

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

第 9 周和第 10 周

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

上周

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