虽然越来越多的组织将设计视为软件开发生命周期以及 API 生命周期中的关键步骤，但很少有组织弄清楚如何有效地大规模设计 API。当你在一个团队中处理有限数量的服务时，设计更容易管理，依赖 PDF 样式指南或 wiki 页面可能足以使每个人保持一致。但是，当设计过程需要在多个团队和数百甚至数千个不同的 API 之间扩展时会发生什么？
创建一个真正可扩展的设计流程
我们推出了 SwaggerHub 来改变团队协同设计和记录 API 的方式。在过去的一年中，我们与数百名 SwaggerHub 用户进行了交流，以更好地了解他们如何能够在多个团队和越来越多的 API 中扩展他们的设计流程。一位用户，CrowdFlower 的工程副总裁 Cameron Befus 解释了他从开源 Swagger 设计工具迁移到 SwaggerHub 以实现更具可扩展性的 API 设计的经验
Crowdflower 一直使用 Swagger 来定义我们的 API 一段时间了，而且由于 SwaggerHub，这个过程变得更加容易。拥有像 Swagger 和 SwaggerHub 这样出色的工具，可以在设计新服务时促进协作，并且可以使记录和集成测试这些服务变得更加容易，这对我们的团队来说是一个巨大的帮助。
Bonotel 的首席信息官 Scot Hastings 也分享了他最近为 API 项目启动新设计流程的经验
随着我们项目的深入，我们意识到我们需要加快流程并使其更高效。我们希望自动生成用户界面，并在内部和外部团队之间促进协作，而不会出现麻烦或沟通问题……通过使我们能够更快地设计和开发 RESTful API，我们可以更快地向市场推出新服务和服务更新，” Hastings 说。“这使得 SwaggerHub 成为我们软件开发生命周期中的关键一环。”
像 CrowdFlower 和 Bonotel 这样的组织通过标准化 OpenAPI (Swagger) 进行 API 设计，并采用一种无缝适应其 API 工作流程的工具，使他们能够在 SwaggerHub 上更有效地协作进行 API 设计，从而能够扩展他们的 API 设计。他们也代表了我们从成功扩展其 API 设计流程的团队中看到的一些关键原则。准备好扩展你的设计流程了吗？以下是你需要采取的一些重要步骤
1. 使你的团队保持一致
良好的 API 设计依赖于参与 API 开发生命周期的所有利益相关者之间的有效协调。如果你的团队在设计要求上不一致，或者如果合适的人员无法获得设计变更的必要可见性，那么当你尝试扩展到一小组 API 之外时，你将遇到摩擦。组织尝试使团队成员在设计流程上保持一致的一种常见方法是通过诸如 Confluence 或 GitHub 之类的协作工具。但是，尽管这些工具在软件开发生命周期中起着至关重要的作用，但要为管理 API 设计工作流程的特定用例配置它们可能会很复杂。SwaggerHub 的构建旨在帮助团队在其 API 的整个生命周期中保持一致。在 SwaggerHub 中，你可以创建组织并邀请团队成员协作进行 API 的设计和文档编制。组织的拥有者可以根据团队成员在设计过程中的参与度，为他们分配角色并管理访问权限。了解有关在 SwaggerHub 中协作的更多信息。
2. 提高设计流程的可见性
与团队在尝试扩展其 API 设计流程时可能面临的一致性挑战类似，还有一个艰巨的任务是提高团队的可见性。我们经常看到，团队将使用开源 Swagger 工具（例如 Swagger Editor 和 Swagger UI）开始他们的 API 设计之旅。虽然这些工具提供了有效建模和可视化 API 所需的功能，但它们并非旨在培养大型 API 团队的协作需求。如果你正在使用 OpenAPI 来处理你的 API 设计，你将需要为你的整个团队提供一个中心位置来访问正在完成的不同服务的设计工作。你还需要确保在发生更改时通知合适的人员，并且你不会将你的可见性限制在分散的电子邮件、Slack 消息和 GitHub 工单中。
3. 减少依赖关系
对于涉及的团队而言，API 开发不仅是一个复杂的过程，而且可能是一个缓慢的过程。团队之间的依赖关系可能是减慢希望从设计转向开始生成代码、起草文档和编写测试用例的团队速度的最大因素之一。团队可以通过 API“模拟”或虚拟化来减少依赖关系的一种方法。 SwaggerHub 中的 API 自动模拟集成使用你在规范中定义的静态响应来创建和维护 API 的模拟。你可以在 SwaggerHub 中创建新 API 时自动创建模拟，也可以稍后随时手动创建模拟。模拟可以帮助你在设计 API 时对其进行测试，也就是说，在开发人员实现它之前。此外，此集成使客户端应用程序开发人员即使在后端准备好之前也可以开始处理他们的部分。无需编写一行代码，你就可以允许 API 消费者针对模拟开发客户端，该模拟保证以兼容的、真实的有效负载进行响应。更重要的是，你可以通过在你的模型定义中使用“示例”构造，直接在 OAS 定义中调整有效负载。
4. 设置并执行设计要求
一家公司对 API 的投资是一项长期事业。设计标准不仅能改进 API 的实现，还能决定 API 的更新方式或新 API 的开发方式。一旦设定了设计指南，就更容易在此基础上进行构建，并允许团队开发 API，从而使组织能够扩展其设计和开发流程。由于设计定义了客户端和服务之间的交互方式，因此设计上的差异会导致服务开发阶段的混乱和开销。这些不一致性只会成倍增加，并且其影响将在 API 生命周期中放大。例如，资源命名不一致的 API 在实现过程中可能会在控制器中使用不同的命名风格。SwaggerHub 通过我们内置的样式验证器来帮助解决设计一致性问题，该验证器会检查您的 API 定义是否符合某些描述标准。例如，贵公司的指南可能要求所有属性都指定示例。样式验证器可帮助您自动化此类检查。在创建样式验证器集成时，您需要指定要执行的检查。
5. 提高设计可重用性
我们经常从使用 Swagger 工具和 OAS 定义其 API 的 API 团队那里听到，当跨数百个 API 定义多个端点时，设计过程可能非常繁琐。当端点共享通用语法并具有相似的定义、路径项、参数和响应时，尤其如此。需要重复单独定义每个端点会减慢设计过程，并导致 API 设计不一致。这就是 SwaggerHub 将域的概念引入设计过程的原因。域是可在多个 API 和其他域之间共享的可重用组件。一个域可以包含以下组件：定义、路径项、参数、响应。用户可以创建和版本化域，然后定义可以存储在其中的可重用组件。用户或 API 上的协作者可以从其他 API 或域引用这些组件。
6. 与您信任的工具集成
能够从设计快速过渡到 API 的文档编制、构建和部署对于建立可扩展的 API 设计流程至关重要。如果当您开始超越 API 生命周期的初始阶段时出现摩擦，即使是最好的设计标准也无法帮助您扩展 API 设计。API 供应商尝试解决此问题的一种方法是在更面向 API 管理的工具之上构建额外的设计功能。虽然拥有一个多合一的解决方案很棒，但它也要求组织被锁定在单个解决方案中，而当您想要引入新工具时，灵活性不高。在 SwaggerHub 中，我们采取了不同的方法——构建一个世界一流的 API 设计平台，供团队用作其 API 设计流程的“事实来源”，然后提供与您的团队信任的工具的无缝集成，以交付出色的 API，包括：Apigee、AWS、Microsoft Azure 或 IBM API Connect 等 API 网关，Bitbucket、GitHub 和 GitLab 等源代码控制平台，以及用于功能测试的 SoapUI 等测试工具。了解有关 SwaggerHub API 生命周期集成的更多信息。
扩展您的设计流程
无论您是已经有了现有的设计流程，还是刚开始使用“设计优先”的 API 开发方法，SwaggerHub 都可以帮助您的团队标准化您的 API 设计，跨团队协作，并使用 OpenAPI/Swagger 集中您的 API 设计工作流程。想了解更多关于 SwaggerHub 如何帮助您的团队扩展设计流程的信息吗？请发送电子邮件至[email protected]以安排演示，或与 SwaggerHub 团队的成员联系。准备好开始了吗？立即免费开始试用 SwaggerHub。