API 开发在过去几年中迅速发展已不是什么秘密。在我们的 2019 年 API 行业状况报告中，我们发现三分之二的组织仅在过去五年内开始开发 API。随着组织扩展其 API 实践，他们开始采用工具来设计与其 OpenAPI 规范（以前称为 Swagger）一致的 API。
SwaggerHub 是一个协作平台，使团队能够组织和管理他们的 REST API，同时扩展和标准化设计实践。
我们经常被刚开始使用该平台的团队问到：
“我的团队应采用哪些最佳实践，才能最大限度地利用 SwaggerHub 进行 API 设计和文档编制？”
以下是 5 个领先的一流 API 设计的 SwaggerHub 最佳实践
1. 在您的组织中定义并强制执行 API 标准化
在我们的 2019 年 API 状况报告中，开发和使用 API 的团队面临的最大挑战是“缺乏标准化”。如果您的团队正在构建和依赖的 API 不是以一致的方式设计的，那么它们可能更难交互和维护。
在 SwaggerHub 中，可以轻松地自动检查样式指南的合规性。您只需选择要应用于组织的样式规则，然后您就可以立即看到哪些 API 需要更新。
当您的团队设计新的 API 时，这些样式规则将显示在编辑器中，以便以标准化、一致的方式构建每个新的 API。
如果您的团队目前正在进行手动审查以确保设计一致性，则此样式检查自动化可以节省大量时间并减少错误。这些审查可以专注于分享知识和最佳实践，而不是标记样式错误。
2. 使用组织、项目和团队管理您的 API 定义和权限
根据您的公司，您可能会处理数百个不同的 API。如果您的组织仅依赖 GitHub 和 Bitbucket 等存储库，则很难清楚地了解谁拥有什么。通过在 SwaggerHub 中管理您的 API，您正在为所有 API 和文档建立集中化的真实来源。
SwaggerHub 中的组织提供了一种简单的方法来管理组拥有的 API 定义以及谁可以访问它们的权限。首先邀请同事成为成员并导入您现有的 API。接下来，将成员分组到团队中，将 API 分组到项目中，并开始使用 SwaggerHub 编辑器设计新的 API。
在内部，SmartBear 拥有一个公司范围的开发组织，然后按他们使用的每个工具组织团队和项目。例如，LoadNinja（SmartBear 的 UI 性能测试平台）的工程团队使用 SwaggerHub 来托管其内部和外部 API 文档。SwaggerHub 充当开发人员协作和了解 LoadNinja 各种内部服务的集中式真实来源。
3. 为常见的 API 组件创建域
在我们的 2019 年 API 状况报告中，75% 的受访者表示，他们认为微服务架构将在未来两年内推动 API 采用的最大增长，而在 2016 年，只有 20% 的人持这种立场。如果您的团队正在扩展 API 开发，那么您的工作中很可能会有常见的组件，例如参数、响应和数据模型。
SwaggerHub 域允许您遵循“不要重复自己 (DRY)”原则，而不是为每个 API 编写 404 错误，而是构建这些常用组件的库。只需在您的错误域中引用 404 错误架构，然后继续设计即可。
这种可重用性意味着您的团队可以减少手动工作，从而降低整个项目的风险。这也意味着，随着更改的进行和标准化元素的演变，只需要更新一个位置。
我们之前提到，设计标准化是 2019 年团队面临的最大挑战。域使您的组织可以使用标准定义。如果您的业务中“客户”或“员工”的定义是一致的，那么最终用户在与您的 API 交互时就可以更容易地知道会发生什么。
4. 使用自动模拟尽早验证设计
您的团队越早测试设计，就越容易对其进行迭代和修复问题。当设计人员使用 SwaggerHub 编辑器来编写和可视化 Swagger 定义时，他们开始通过内置的自动模拟（由与另一个名为 VirtServer 的 SmartBear 工具集成提供）尽早验证行为。
此 VirtServer 集成会自动创建并维护 SwaggerHub 中定义的 API 的半静态模拟。此模拟会在您每次保存 API 时更新，这意味着您不再需要特意创建模拟服务。使用 VirtServer 生成的预览与您的团队一起迭代设计，只需点击几下即可完成。
自动模拟为设计人员提供了有关其工作的即时反馈，但它也会影响您的其余软件团队的工作方式。有了模拟，开发人员可以并行开始开发客户端应用程序，而不是等待后端 API 工作完成。
5. 将 SwaggerHub 纳入您的 CI/CD 管道策略
许多团队现在希望通过集成整个软件开发生命周期中的不同工具来构建 CI/CD 管道。
SwaggerHub 与 AWS、Microsoft Azure、IBM API Connect 和 Apigee 等 API 管理平台具有原生集成，因此很容易集成到您的交付管道中。
当 SwaggerHub 成为组织 REST API 的真实来源时，它最有用。通过将 API 定义与 GitHub、Bitbucket 和 GitLab 等源代码控制存储库同步，您可以确保跨平台和跨组织的文档和代码的版本控制一致性。团队甚至可以将 SDK 和代码模板推送到这些存储库系统中，从而消除构建新服务的大量准备工作，并让开发人员首先专注于逻辑和功能。
您还可以设置 SwaggerHub Webhooks 来创建自定义工作流程。例如，CrossBrowserTesting.com（SmartBear 的一个 Web 测试平台）背后的团队使用 SwaggerHub 来定义其 API 并在一个地方管理文档。通过 Webhooks，他们将 SwaggerHub 连接到一个模板工具，该工具可以实时获取 JSON 定义文件并以统一的方式显示它。
入门指南
如果您的团队已经在使用 SwaggerHub，如果您对这些最佳实践有任何疑问，请随时联系我们。如果您尚未在使用 SwaggerHub，您可以创建一个免费帐户并导入您现有的 API 来开始使用。