虽然越来越多的组织将设计视为软件开发生命周期及其 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 在设计过程中引入了 域（Domains） 的概念。域是可在多个 API 和其他域之间共享的可重用组件。一个域可以包含以下组件：定义、路径项、参数、响应。用户可以创建和版本化域，然后定义可存储在其中的可重用组件。这些组件可以由用户或 API 上的协作者从其他 API 或域中引用。
6. 与您信任的工具集成
能够快速地从设计阶段过渡到 API 的文档化、构建和部署，对于建立可扩展的 API 设计流程至关重要。即使是最好的设计标准，如果在 API 生命周期初始阶段之后开始推进时遇到阻碍，也无法帮助您扩展 API 设计。API 供应商解决此问题的一种方法是在更侧重于 API 管理的工具之上构建额外的设计功能。虽然拥有一个一体化解决方案很棒，但它也要求组织被锁定在单一解决方案中，当您想要引入新工具时缺乏灵活性。在 SwaggerHub 中，我们采用了不同的方法——构建一个世界级的 API 设计平台，供团队用作其 API 设计流程的“事实来源”，然后提供与您的团队信任的工具的无缝集成，以交付出色的 API，包括：API 网关，如 Apigee、AWS、Microsoft Azure 或 IBM API Connect；源代码控制平台，如 Bitbucket、GitHub 和 GitLab；以及用于功能测试的测试工具，如 SoapUI。了解更多关于 SwaggerHub API 生命周期集成的信息。
扩展您的设计流程
无论您已有现成的设计流程，还是刚开始采用“设计优先”的 API 开发方法，SwaggerHub 都能帮助您的团队标准化 API 设计，实现跨团队协作，并利用 OpenAPI/Swagger 集中化您的 API 设计工作流程。想了解更多关于 SwaggerHub 如何帮助您的团队扩展设计流程的信息？请给我们发送电子邮件 [email protected] 以安排演示，或与 SwaggerHub 团队成员联系。准备好开始了吗？立即免费试用 SwaggerHub。