OpenMRS 项目

本页面包含“Google 文档季”接受的技术写作项目的详细信息。

项目摘要

开源组织：
OpenMRS
技术文档工程师：
索拉布语
项目名称：
扩展 REST API 的用户友好 GitHub 文档
项目时长：
标准时长（3 个月）

Project description

主要目标

完善了基于 OpenMRS Swagger 的 REST API 文档，添加了使用该 API 的指南。

项目说明

OpenMRS REST API 是开发者访问 OpenMRS 数据的主要机制之一。目前已经有基于 Swagger 的 OpenMRS Webservices API 文档以及基于 GitHub 的静态文档，我们计划在本季文档扩展该文档。

简要概述

按照 Burke 的建议对 OpenMRS Talk 进行了一些研究后，我了解到这个项目早在 2017 年就属于 GSOC 项目。Gayan Weerakutti 是 Gayan Weerakutti，主要目的是通过改进其 Swagger 规范以及改进其 Swagger 规范的生成方式来改进现有的 OpenMRS REST API 文档，从而生成更完善的 Swagger 文档版本。 在此 OpenMRS 演讲博文中总结了该项目中所取得的所有相关细节，这些细节都非常实用。

然后，在 2019 年对这个项目进行了改版，从 Swagger 文档着手，在这方面进行了一些调整。我们改为编制了一个适合 GitHub 的静态文档，我们将在本季的 Google 文档中对其进行扩展。

因此，我想简要介绍一下当前的项目提案：

  1. 编写一些热门语言（特别是 java 和 javascript）的示例。
  2. 为 Slate 文档添加 Playground 支持，就像 Swagger 的“try-out”功能一样。
  3. 重构和改进到目前为止已经完成的工作。
  4. 查找并添加缺失的资源。
  5. 向文档的控制台部分添加更多说明

详细说明

  1. 提供不同语言的示例。

我建议在 java 中添加基于 SDK 的示例，然后添加 Retrofit 示例，我认为这样会更深入地说明我们的文档，因为使用某种语言（如 JavaScript）添加示例比添加 Retrofit 示例的帮助不大，因为我在开发 OpenMRS Android 客户端时使用过这些 REST API，而且每当我需要使用专门针对 Android 的端点时，都没有资源可供查询。 鉴于我在 Android 客户端中处理 OpenMRS API 端点的经验，我可以在此认真地做出一些优质的示例。 我将与导师讨论此问题，并一起讨论如何决定。 此外，除了为支持的操作添加示例之外，我们还应该添加使用某些编程语言向 OpenMRS 服务器进行身份验证的示例。我们目前只有 curl 示例。

  1. 为测试 API 示例添加 Playground 支持

我在托管于演示服务器上的 OpenMRS 的 Swagger 文档中使用过此功能，它在任何 API 文档中都是一种非常方便的工具。我在这里做了一点研究，将 Swagger 界面规范嵌入当前的静态文档中并不难。使用“显示隐藏”切换开关和我们当前的 Swagger 文档代码。 这样一来，我们甚至可以确保 tryout 功能在当前的 API 规范下保持有效状态，我认为这是将 Playground 功能集成到当前静态文档中的一种方式。

  1. 重构和改进到目前为止已经完成的工作
检查当前的 curl 示例

此部分是本项目今年重点讨论的内容之一。目前，GitHub API 文档中只有 curl 示例，其中一些示例无法直接在演示服务器上运行，无法直接从浏览器进行检查。我将测试当前的所有端点，并维护一个简单的文档，其中包含运行这些 curl 请求时所获得的各种 curl 示例的响应。如果需要，除了 Swagger 文档中内置的试用功能之外，我还会使用 Postman 完成这项任务。

部分示例缺少 API 响应

已为当前 curl 示例添加了一些响应，但有些 curl 示例没有响应。我认为，即使响应并不冗长（在执行资源完全清除等操作中通常就是如此），但我们应该提供一个示例 JSON API 响应，尽管我们已经记录了所有可能的响应代码以及获取这些代码的原因，我认为这会使整个 API 文档中的示例更加统一！！

缺少各种操作的工作示例

我认为这将是重构 API 文档中之前所完成工作的最重要部分，文档中提供了可直接使用 c网址 执行的具体示例，但其中一些示例比较抽象，可以很好地引用经验丰富的开发者，但让新手处于困境。 正如我在 OpenMRS 中的这篇博文中所了解到的，好的示例意义非凡，除了添加工作示例之外，我们还可以支持语法突出显示，这项工作确实不多。 它几乎与可选广告捆绑在一起，这让我可以非常轻松地实现这一点，

由于 Burke 在他的博文中多次强调，希望使用简单性和描述性来代替良好的界面和出色的界面，因此我会遵循这些原则，与目前正在开发 OpenMRS Webservices API 并参与社区的开发者交谈，使之前记录的端点尽可能具有描述性，就像我在演讲帖子中向我收集这里不清楚的表单资源的说明一样。我真的会优先处理这些事情，与导师交流，并确定哪些事情能够真正为文档增添价值，并且需要先完成这些工作。

添加用例作为明确标题

我看过很多 API 文档，只是为了弄清楚它们，并发现所有用例都以显式标题形式呈现。尽管在资源和子资源定义之后，我们确实有一些没有明确可见的用例与定义和示例混淆。我认为我们应该努力将用例分离为单独的实体，让开发者无需在文档中进行搜索。

  1. 查找和记录缺失的资源

    当前的项目状态中列出了此处列出的资源，但在看到此处的 swagger 文档的最新版本后，我可以在 GitHub 友好的 API 文档中找到许多可以添加到当前资源套件的资源，并说明了 2019 年文档季期间使用其他资源完成的说明。 我会讨论需要添加到文档中的主题，并相应地添加它们。

总结

我加入 OpenMRS 社区已有一段时间了。我是 Android 客户端项目的积极贡献者，我经常与 API 进行交互以与服务器进行交互。因此，我觉得我可以在这个项目中很好地扩展 API 文档，因为我能以开发者的身份查看我的工作，并评估这是否真的能简化其他开发者的工作。我已经熟悉了用于此处托管的方便用户使用的文档库的工具，我也对此代码库进行了一些贡献，以便熟悉该代码库和工具，例如将其改进为优质的 REST API。

我每周都会通过演讲帖子来分享进展情况，这有助于从社区获取反馈，并与导师和社区保持密切联系，在这段文档记录中充分发挥自己的价值。