使用 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 规范 替换您的 API 规范。