本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- OpenMRS
- 技术文档工程师：
- 索拉布节
- 项目名称：
- 扩展 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 的主要目标是改进 OpenMRS REST API 的现有文档，方法是改进其 Swagger 规范，并改进其 Swagger 规范的生成方式，从而生成更好的 Swagger 文档本身。 这篇 OpenMRS 演讲博文中总结了此项目的所有相关细节，并提供了很大的帮助。
然后，在 2019 年，该项目进行了改版，从 Swagger 文档调整开始，制作出更多变体。不过，我们开发了一个适用于 GitHub 的静态文档，并将在本季的 Google 文档中扩展该文档。
下面，我将简要介绍当前的项目方案：
- 编写一些热门语言（特别是 java 和 javascript）的示例。
- 为 Slate 文档添加 Playground 支持，就像 Swagger 的“try-out”功能一样。
- 重构和改进到目前为止已经完成的工作。
- 查找并添加缺少的资源。
- 为文档的控制台部分添加更多说明
详细说明
- 提供不同语言的示例。
我建议在 java 中添加基于 SDK 的示例，然后添加 Retrofit 示例，我认为这些示例会让我们的文档更深入，因为再添加一种语言（例如 JavaScript）的示例并没有添加 Retrofit 示例的帮助那么大，因为我在处理 OpenMRS Android 客户端时使用了这些 REST API，而且每当我需要使用专门针对 Android 的端点时，都没有资源可查询。 鉴于我在 Android 客户端中处理 OpenMRS API 端点的经验，我可以在此提供一些优质的示例。 我将与导师讨论此事宜，并一起商讨最终决定。 此外，除了添加支持的操作示例之外，我们还应添加使用某些编程语言向 OpenMRS 服务器进行身份验证的示例。目前，我们只有 curl 示例。
- 为测试 API 示例添加 Playground 支持
我在演示服务器上托管的 OpenMRS 的 Swagger 文档中使用过此功能，这在任何 API 文档中都是一种非常方便的工具。我在此进行了一些研究，将 Swagger 界面规范嵌入到当前的静态文档中并不难。使用显示/隐藏切换开关和当前的 swagger 文档代码。这样，我们甚至可以确保试用功能在当前的 API 规范下保持有效，我认为我们可以将 Playground 功能集成到我们当前的静态文档中。
- 重构和改进到目前为止的工作
检查当前的 curl 示例
本部分是该项目今年的重点内容之一。目前，GitHub API 文档中只有 curl 示例，其中一些示例无法直接在演示服务器上运行，无法直接从浏览器进行检查。我将测试所有当前端点，并维护一个简单的文档，其中包含运行这些 curl 请求时所获得的各种 curl 示例响应。 如果需要，除了 Swagger 文档中内置的试用功能外，我还会使用 Postman 完成此任务。
部分示例缺少 API 响应
已为当前的 curl 示例添加一些响应，但部分 curl 示例没有响应。 我认为，即使响应并不冗长（在执行资源完全清除等操作中通常就是如此），但我们还是应该提供一个示例 JSON API 响应。尽管我们已经记录了所有可能的响应代码以及获取这些响应代码的理由，但我认为这会使 API 文档中的示例更加统一！！
缺少各种操作的工作示例
我认为这将是重构 API 文档中之前完成的工作的最重要部分，文档中提供了可以直接使用 c网址 执行的具体示例，但其中一些示例较为抽象，可为经验丰富的开发者提供很好的参考，但让新手感到厌烦。 正如我在 OpenMRS 中的这篇博文中了解到的，好的示例是无比珍贵的，除了添加工作示例之外，我们还可以支持语法突出显示，这项工作确实不多，但基本上是与可选广告捆绑在一起的，正如我在这里发现的那样，
由于 Burke 在他的博文中多次强调，倾向于在文档中使用简单性和描述性来代替良好的界面和出色的界面，因此我会遵循这些原则，通过与目前正在开发 OpenMRS Webservices API 并参与社区的开发者交流，尽可能使之前记录的端点具有描述性，就像我在演讲帖子中向我收集表单的属性类型说明一样。我会把工作重点放在优先事项上，与我的导师交流，确定哪些是真正为文档增添价值且需要先完成的事情。
添加用例作为明确标题
我查看了许多 API 文档，只是为了掌握它们的窍门，并且发现所有用例都有作为明确标题的用例，尽管我们确实有一些用例不明确可见，它们在资源和子资源定义之后的定义和示例中有点融合。我认为我们应该努力将用例分离为单独的实体，这样开发者就无需在文档中进行推断，而是在定义中找出用例。
查找和记录缺失的资源
当前的项目状态包含此处列出的资源。不过，通过查看此处的最新版本的 Swagger 文档，我可以在适用于 GitHub 的 API 文档中，找到可以添加到当前资源套件中的许多资源，以及通过其他资源在 2019 年发布季期间完成的说明。 我将讨论需要添加到文档中的主题，并适当添加这些主题。
总结
我加入 OpenMRS 社区已有一段时间了。我是 Android 客户端项目的积极贡献者，我经常与 API 进行交互以与服务器进行交互。因此，我觉得我可以非常轻松地扩展 API 文档，因为我可以自己了解自己的工作，并评估它是否真的能简化其他开发者的工作。我已经熟悉了用于此处托管的方便用户使用的文档库的工具，我也对此代码库进行了一些贡献，以便熟悉该代码库和工具，以改进其文档。
我一定会每周通过一个演讲帖子传达进展情况，这有助于获取社区的反馈，并与我的导师和社区密切合作，以便充分利用这段记录工作。