在 SwaggerHub 中借助比较与合并功能改进您的 API 文档工作流程

API 描述格式（如 Swagger）是 API 提供者和最终消费者之间的契约，它以人类和机器均可读的格式清楚地详细说明了 API 的所有资源和操作。使用 Swagger 文档化您的 RESTful API 可以简化开发、改善发现并为最终消费者提供更好的整体集成体验。 作为使用 Swagger 定义 API 的提供者，您有责任使该契约保持最新，这通常需要管理 Swagger 定义的多个版本。 或者，如果您采用“代码优先”的 Swagger 方法（这意味着需要使用注解从 API 代码生成 Swagger 规范），您可能会发现需要进行一些调整才能为您的 API 创建一个精心设计的定义。 无论您的团队采用何种方法使用 Swagger 定义 API，很可能都有许多不同技能和职责的人员参与到此过程中。

让合适的人参与 API 文档

助您的文档工作流程的合适工具

隆重推出 SwaggerHub 的比较与合并功能

1. 在 SwaggerHub 中，打开您的 API 进行编辑。切换到所需的版本。
2. 点击编辑器右上角的“齿轮”图标，从菜单中选择 比较和合并 API：
3. 在后续对话框中，选择 与 SwaggerHub 中的规范比较：
4. 在下一个对话框中，指定用于比较的用户名、API 和 API 版本：

1. 点击 下一步。SwaggerHub 将验证 API 是否可访问。

1. 在 SwaggerHub 中，打开您的 API 进行编辑。切换到所需的版本。
2. 点击编辑器右上角的“齿轮”图标，从菜单中选择 比较和合并 API。
3. 在后续对话框中，选择 与外部规范比较
4. 在下一个对话框中，输入所需的 JSON 或 YAML API 的 URL，或在硬盘上指定 API 文件：
5. 点击 获取。SwaggerHub 将加载指定的 API 并检查其是否有效。

1. 点击窗口右侧或左侧突出显示的差异行（或块）。SwaggerHub 会将块从窗口左侧复制到右侧（即复制到您的 API），并移除高亮显示。它还会增加“撤销”按钮中的计数器。
2. 点击 撤销 以在需要时还原最近的批准。要还原多次批准，请多次点击“撤销”。
3. 合并所有所需差异后，点击 保存更改 以保存更改。这将 替换 您的 API 规范为已更改的规范。