使用Hoppscotch工具编写API文档指南

在成为文档工程师之前，我对API文档了解不多。公司给了我一个任务，让我为公司提供的API端点编写文档。我开始了这段学习旅程，并开始学习如何编写API文档以及相关的工具。
我将分享在这段旅程中所学到的所有知识。

在这系列文章中，我谈到了如何用Postman写API文档。本文将介绍用Hoppscotch编写API文档。

……

API是大多数现代应用程序的关键部分，为开发者提供清晰详细的文档对于他们理解、互动以及高效地使用API来说非常关键。Hoppscotch，一个基于网页的API开发工具，因其易用性和强大的功能而迅速受到欢迎。它不仅是一个多功能的API测试平台，也是一个以易于访问和用户友好的方式记录API的强大工具。

……

目录

1. 关于Hoppscotch的介绍
2. 使Hoppscotch成为API文档理想选择的特点
3. 如何使用Hoppscotch记录API文档
4. 使用Hoppscotch编写API文档的最佳实践
5. Hoppscotch在API文档中的优点
6. 总结

……

Hoppscotch 简介

Hoppscotch 是一个轻量级的开源 API 开发工具，用于提高 API 测试和探索的效率。最初以 Postwoman 的名字推出，后改名为 Hoppscotch，并不断进化，增加了更多高级功能，同时保持了一个易于访问的浏览器界面。

专为开发者设计，由开发者创建，Hoppscotch的核心目标是简化测试和记录RESTful API的流程。它提供了一个流畅且用户友好的界面，用户可以发送请求、接收响应并以有组织的方式存储数据，使其成为API测试和文档的理想工具。

此处省略内容

让Hoppscotch成为理想的API文档特性

1. 交互式API测试功能

Hoppscotch允许用户实时发送请求并查看响应，从而更方便地记录API行为，尤其是在记录响应格式、状态码和错误处理方面特别有用。

1. 收藏夹和文件夹

Hoppscotch允许用户将请求归类到收藏夹和文件夹中，按照API的端点和功能进行结构化安排。这些收藏夹可以充当文档库，便于对相关API请求进行分类、引用或分享。

1. 环境变量

使用环境变量，用户可以在一个地方设置和管理如API密钥、令牌和URL等值。这不仅减少了冗余，还保持了文档的整洁，敏感或常变的数据可以集中管理和随时更新。

1. 实时协作

Hoppscotch 包括实时协作，使团队成员能够同时编辑和审阅文档。该功能确保团队成员的编辑保持一致，并允许即时反馈，这对于创建准确和及时更新的文档至关重要。

1. 导入和导出选项

Hoppscotch 支持导入和导出集合文件，这意味着用户可以轻松地分享文档或备份他们的工作。支持的格式包括Postman集合文件，这对于正在从Postman迁移或与Postman共同使用文档的团队来说非常理想。

等等

在 Hoppscotch 中记录 API 非常简单直接，它让你能够方便地组织、描述和分享 API 信息。

(hoppscotch.io)

（此处省略）

第一步：建立一个集合对象

Collections 在 Hoppscotch 中作为“集合”来集中相关 API 请求，便于整理端点。

1. 导航到收藏夹: 在右侧边栏，点击 收藏夹。
2. 创建一个新的收藏夹: 点击 新增 按钮，给收藏夹命名，并添加一个简短的描述。这可以是你的 API 名称或者一个逻辑分组，例如 “用户管理接口”。
3. 保存收藏夹: 设置完成后，保存收藏夹以开始添加请求。

……

步骤 2: 添加和记录请求

每个你添加到文档中的端点都会在 Hoppscotch 中作为请求添加。这里是如何添加并记录一个请求的方法。

1. 创建新请求。

• 在您的收藏中，点击 + 添加请求 按钮。
• 为请求命名（例如，“获取用户详情”），并选择相应的 HTTP 方法（如 GET、POST、PUT 等）。

• 输入端点 URL，例如 https://jsonplaceholder.typicode.com/users。

  1. 设置请求详情：
• 参数： 在“Params”标签页中添加任何查询参数，如过滤选项 (?userId=1)。
• 头部： 输入任何必要的头部信息，例如用于认证的 Authorization。

• 正文： 如果请求方法是 POST、PUT 或 PATCH，则以 JSON 或其他所需格式添加请求正文。

  1. 添加描述和注释：

• 请求说明: 简要描述该端点的功能。例如，“检索系统中所有用户的详细信息。”

• 参数描述: 对于每个参数，指定其用途和有效值，例如“userId - 用户的ID（整数），可选。”

• 响应描述: 说明返回的主要字段、状态码和错误消息。例如：

• 成功（200）: 返回包含id、name和email的用户信息的JSON数组。

• 错误（404）: 如果找不到用户ID，返回“未找到”信息。

第三步：使用环境变量来实现代码复用

环境变量使您的文档能够适应不同的环境（例如开发、staging 和生产环境）。这里是如何设置它们的方法：

1. 去到环境部分： 在左边栏中，找到 环境 选项。
2. 新建一个环境： 设置环境变量，比如 baseURL、API_KEY 或常用的重复数据。
3. 在请求中使用变量： 用变量替换死的 URL 和敏感信息，例如 {{baseURL}}/users。让您的文档更灵活且更清晰。

此处省略

步骤 4：测试并记录响应

Hoppscotch的一个强项是它可以发送请求并立即显示反馈，这有助于验证您的文件。

1. 发送请求： 点击 发送 查看响应。
2. 响应记录： 在响应部分做如下事项：

• 添加关于响应结构的笔记。

• 描述每个字段（例如，id - 唯一标识符，title - 帖子标题等）。

• 记录任何错误信息或特殊情况。

  1. 保存响应示例： 为了更清晰明了，您可以保存一个响应示例，或者复制粘贴到请求描述中。
• • *

第五步：整理和分享文档

1. 通过文件夹组织端点： 将相关的请求分组到集合中的文件夹。例如，所有用户相关的端点可以放在一个“用户”文件夹里。
2. 导出或分享文档：

• 要分享记录的API，可以通过点击导出按钮并选择导出为JSON等格式来完成。

• Hoppscotch还支持通过生成一个链接来分享集合内容，团队成员可以使用此链接查看或导入文档。

• • *

假设你要文档化一个获取或检索用户信息的GET请求，如下：

• 名称: 获取用户信息
• 方法: GET
• URL: https://jsonplaceholder.typicode.com/users/1
• 描述: 根据用户ID获取用户信息。

• 参数:

• userId (可选, 整数): 要获取的用户的ID。
• Headers: Authorization (Bearer Token) - 访问用户资料需要提供授权。

• 预期响应:

• 成功 (200 状态码): 返回包含 id, name, 和 email 字段的 JSON 格式用户信息。

• 错误 (404 状态码): 如果 userId 与现有用户不匹配，则返回“用户未找到”的消息。

• • *

1. 命名和结构的一致

为集合、文件夹和请求制定标准化的命名规范。一致性有助于用户在文档中导航，并快速找到相关端点。

1. 详细描述每个部分

不要假设其他人了解你的API请求的背景。确保每个端点、方法和参数提供清晰简洁的描述，确保包含所有必要细节。

1. 测试并记录错误案例

只记录成功案例容易忽略重要信息。确保测试并记录可能的错误回应，包括状态码和错误消息。这样可以帮助用户了解如何应对异常情况。

1. 利用评论和注释功能

在您的收藏中使用评论来提供必要的额外信息。评论是解释复杂请求或提供端点使用方面的见解的绝佳方式，而不会使主要文档变得混乱。

1. 保持文档更新

API经常发生变化，端点会被添加、修改或废弃。确保你定期审查和更新Hoppscotch的文档，以保证准确性。

(hopscotch.io)

1. 直观的界面

Hoppscotch的界面简洁明了，干净整洁且易于操作。与功能更复杂的工具相比，它不需要复杂的配置过程，也没有令人望而生畏的学习曲线，无论是经验丰富的开发者还是新手，都能轻松上手。

1. 实时反馈

通过即时响应API请求的方式，Hoppscotch可以实现文档中端点的实时验证。开发人员可以直接在测试端点时验证文档的准确性。

1. 开源灵活性

作为开源工具，这意味着Hoppscotch可以根据需要进行定制或集成到现有工作流程中。开发人员可以对代码库进行贡献，团队还可以在此基础上扩展功能，以更好地满足自身需求。

1. 团队协作功能

Hoppscotch的实时协作功能支持动态的文档工作流程，非常适合敏捷团队的使用。多名成员可以贡献或审查API说明文档。

1. 支持多种API类型

虽然主要用于RESTful API，Hoppscotch还支持GraphQL和WebSocket请求，使其适合多种API文档需求。

Hoppscotch（//hoppscotch.io）是一款全面且用户友好的API文档解决方案。其交互式的界面、实时测试的能力以及协作工具，使得它成为传统API文档工具的一个强有力替代品。开发人员可以通过组织文档集合、利用环境变量以及仔细记录成功和错误的响应来创建强大且准确的文档，从而增强API的易用性。

星🌟跳Hopscotch On GitHub

你知道在开发者手册上，你可以找到各种主题和语言的小教程，非常适合忙碌的生活方式吗？