毋庸置疑，API 开发在过去几年中取得了飞速发展。在我们的《2019 年 API 行业报告》中，我们发现三分之二的组织在过去五年内才开始开发 API。随着组织扩大其 API 实践，它们开始采用工具来根据 OpenAPI 规范（前身为 Swagger）设计其 API。
SwaggerHub 是一个协作平台，使团队能够组织和管理其 REST API，同时扩展和标准化设计实践。
我们经常收到刚开始使用该平台的团队的提问：
“我的团队应该采用哪些最佳实践，才能充分利用 SwaggerHub 进行 API 设计和文档化？”
以下是使用 SwaggerHub 实现最佳 API 设计的 5 大实践
1. 在整个组织内定义并强制执行 API 标准化
在我们的《2019 年 API 行业报告》中，团队开发和使用 API 面临的首要挑战是“缺乏标准化”。如果您的团队正在构建和依赖的 API 没有以一致的方式设计，它们将更难以交互和维护。
在 SwaggerHub 中，自动化样式指南合规性检查非常容易。您只需选择要应用于组织的样式规则，即可立即看到哪些 API 需要更新。
当您的团队设计新的 API 时，这些样式规则将显示在编辑器中，以便每个新的 API 都以标准化、一致的方式构建。
如果您的团队目前正在进行手动审查以确保设计一致性，这种样式检查自动化可以节省大量时间并减少错误。这些审查不再需要标记样式错误，而是可以专注于分享知识和最佳实践。
2. 使用组织、项目和团队管理您的 API 定义和权限
根据您的公司情况，您可能正在处理数百个不同的 API。如果您的组织仅依赖 GitHub 和 Bitbucket 等代码仓库，很难清楚地了解谁拥有什么。通过在 SwaggerHub 中管理您的 API，您将为所有 API 和文档建立一个集中的真相来源。
SwaggerHub 中的组织提供了一种简单的方法来管理组拥有的 API 定义以及谁可以访问它们的权限。首先邀请同事成为成员并导入您现有的 API。接下来，将成员分组到团队中，将 API 分组到项目中，并开始使用 SwaggerHub Editor 设计新的 API。
SmartBear 内部有一个全公司范围的开发组织，然后按每个工具组织团队和项目。例如，SmartBear 的 UI 性能测试平台 LoadNinja 的工程团队使用 SwaggerHub 来托管其内部和外部 API 文档。SwaggerHub 充当开发人员协作和理解 LoadNinja 各种内部服务的中央真相来源。
3. 为常见的 API 组件创建域
在我们的《2019 年 API 行业报告》中，75% 的受访者表示他们相信微服务架构将在未来两年内推动 API 采用的最大增长，而在 2016 年只有 20% 的人持此观点。如果您的团队正在扩展 API 开发，那么您的工作中很有可能存在通用组件，例如参数、响应和数据模型。
SwaggerHub 域允许您通过构建这些通用组件的库来遵循“不要重复自己”（DRY）原则，而不是为每个 API 编写 404 错误。只需在您的错误域中引用 404 错误模式，然后继续设计。
这种可重用性意味着您的团队手动工作量更少，从而降低了项目风险。这也意味着，随着更改的进行和标准化元素的演变，只需要更新一个位置。
我们之前提到，设计标准化是 2019 年团队面临的最大挑战。域使您的组织能够使用标准定义。如果“客户”或“员工”的定义在您的业务中保持一致，那么最终用户在与您的 API 交互时就更容易知道会发生什么。
4. 使用自动模拟尽早验证设计
您的团队越早测试设计，就越容易对其进行迭代和修复问题。当设计人员使用 SwaggerHub Editor 编写和可视化 Swagger 定义时，他们会通过与另一个 SmartBear 工具 VirtServer 集成的内置自动模拟功能，尽早验证行为。
此 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 Webhook 来创建自定义工作流。例如，SmartBear 的 Web 测试平台 CrossBrowserTesting.com 背后的团队使用 SwaggerHub 在一个地方定义其 API 并管理文档。通过 Webhook，他们将 SwaggerHub 与一个模板工具连接起来，该工具实时获取 JSON 定义文件并以统一的方式显示。
入门
如果您的团队已经在使用 SwaggerHub，如果您对这些最佳实践有任何疑问，请随时联系我们。如果您还没有使用 SwaggerHub，可以通过创建免费账户并导入现有 API 来开始使用。