本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- OpenMRS
- 技术文档工程师：
- 索拉卜
- 项目名称：
- 针对 REST API 扩展方便用户使用的 GitHub 文档
- 项目时长：
- 标准时长（3 个月）
Project description
主要目标
改进了基于 Swagger 的 OpenMRS 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 的静态文档，并将在本季文档中对其进行扩展。
我打算介绍的当前项目提案简要如下：
- 用一些流行语言（特别提到了 Java 和 JavaScript）举例。
- 为 Slate 文档添加了 Playground 支持，就像 Swagger 的“试用”功能一样。
- 重构和改进到目前为止所做的工作。
- 查找并添加缺少的资源。
- 在文档的控制台部分添加了更多说明
详细说明
- 提供不同语言的示例。
我建议添加基于 SDK 的 Java 示例，然后添加 Retrofit 示例，我认为这将使我们的文档更加深入，因为添加 JavaScript 等其他语言的示例不会像添加 Retrofit 示例那样有用，因为我在处理 OpenMRS Android 客户端时使用了这些 REST API，但每当我需要使用专门针对 Android 的端点时，都没有可查找的资源。 鉴于我在 Android 客户端中处理 OpenMRS API 端点的经验，我能够在此认真提供一些优质示例。 我将与我的导师讨论此事宜，并研究最终决定。 此外，除了添加支持的操作示例之外，我们还应添加使用某些编程语言对 OpenMRS 服务器进行身份验证的示例。目前，我们仅提供了 curl 示例。
- 为测试 API 示例添加了 Playground 支持
我在托管在演示服务器上的 OpenMRS 的 Swagger 文档中使用了此功能，它是任何 API 文档中都非常方便的工具。我做了一些研究，发现将 Swagger-UI 规范嵌入到当前的静态文档中并不难。使用显示/隐藏切换开关，并使用我们当前的 Swagger 文档代码。 通过这种方式，我们甚至可以确保试用功能在当前的 API 规范中保持有效，我认为我们可以将 Playground 功能集成到当前的静态文档中。
- 重构和改进到目前为止完成的工作
查看当前的 curl 示例
本部分是今年此项目的主要重点之一。目前，GitHub API 文档中只有 curl 示例，其中一些示例无法直接在演示服务器上运行，无法直接从浏览器中进行检查。我将测试所有当前端点，并维护一个简单的文档，其中包含我们在运行这些 curl 请求时收到的各种 curl 示例响应。如果需要，除了 Swagger 文档中的内置试用功能外，我还将使用 Postman 来完成此任务。
部分示例缺少 API 响应
我们为当前的 curl 示例添加了一些响应，但部分 curl 示例没有响应。 我认为，即使响应不冗长（在完全清除资源等操作中通常会出现这种情况），我们也应该提供一个示例 JSON API 响应，尽管我们记录了所有可能的响应代码以及获取这些代码的原因。我认为这会使 API 文档中的示例更加统一！！
缺少关于各种操作的工作示例
我认为，这是在 API 文档中重构之前完成的工作最重要的部分。文档中有一些具体的示例，可以直接使用 c网址 执行，但其中一些示例有点抽象，对于有经验的开发者来说，这些示例非常有用，但对于新手来说，这些示例会让人感到困扰。 我从 OpenMRS 讲座的这篇文章中了解到，好的示例是无价之宝，因此除了添加工作示例之外，我们还可以支持语法突出显示，这实际上并不需要太多工作，因为它几乎与 Slate 捆绑在一起，正如我在这里发现的那样，这很容易做到，
正如 Burke 在他的博文中多次强调的那样，我更喜欢文档中的简洁性和描述性，而不是良好的界面和亮丽的界面，我会遵循这些原则，并通过与目前正在开发 OpenMRS Webservices API 的开发者和与社区互动，尽量使之前记录的端点尽可能具有描述性，就像我在演讲帖子中为我收集此处不清楚的表单资源属性类型的描述一样。我会按照优先级来处理事项，与导师沟通，并确定哪些事项真正有助于提升文档的价值，以及哪些事项需要优先完成。
将“使用场景”添加为显式标题
为了熟悉 API，我查看了许多 API 文档，发现它们都将用例作为显眼的标题，虽然我们确实有用例，但它们并未明确显示，而是在资源和子资源定义后面的定义和示例中有所融合，我认为我们应该努力在文档中将用例作为单独的实体进行分离，这样开发者就不必真正搜索定义来推断用例，而是可以直接查找它们。
查找并记录缺失的资源
当前项目状态中列出了一些资源，但在查看最新版 Swagger 文档后，我发现有许多资源可以添加到 GitHub 友好型 API 文档中的当前资源套件中，并在说明中说明这些资源是如何在 2019 年文档季期间与其他资源一起完成的。 我会讨论需要添加到文档中的主题，并适当地添加这些主题。
总结
我加入 OpenMRS 社区已有一段时间了。我是 Android 客户端项目的活跃贡献者，经常与 API 互动以与服务器互动。因此，我认为自己非常适合参与这个扩展 API 文档的项目，因为我可以以开发者的身份审视自己的工作，并评估它是否真的能够简化其他开发者的工作。我已经熟悉了此处托管的用户友好型文档仓库所使用的工具，也向该仓库做出了几项贡献，以便熟悉仓库和工具（例如 slateUI）。由于 API 的质量取决于其文档，因此我非常乐意通过改进文档来改进 OpenMRS Rest API。
我会每周通过对话帖子分享进展，以便从社区获取反馈，并与导师和社区密切合作，充分利用这段时间来编写文档。