将 API 视为业务和战略举措的驱动力是最近才有的发展，现在各组织已开始在其 API 战略上投入大量资金。
那些在制定 API 战略方面进行大量投资的组织已超越了传统的技术领导者。从金融服务到医疗保健，从教育到制造业，以及更多行业，都看到了 API 采用率的显著增长。
与此同时，API 描述格式（如 OpenAPI 规范，以前称为 Swagger 规范）的采用率也呈爆炸式增长，它们为您的 API 提供了一种与语言无关且人类可读的契约，允许机器和人类都能解析和理解 API 的预期功能。
如今，成千上万的组织（无论大小）都在使用 OpenAPI 规范 (OAS) 来简化其 API 的开发并推动其采用。在组织的内部和外部 API 中实施 OAS 带来了一系列独特的挑战，尤其是在尝试跨多个不同团队扩展多个 API 项目时。
这时，拥有一个能够促进 OAS 实施的工作流程就会派上用场。
本电子书的目标是介绍一种在您的组织内使用 OAS 的易于遵循的工作流程。
转型为 API 平台
应用程序编程接口（简称 API）早在个人电脑发明之前就已存在，并且一直被视为技术资产。然而，在过去的十年中，互联网、社交媒体、电子商务和移动设备造成的信息颠覆，使得更多组织认识到 API 作为数据和服务分发渠道的重要性。
今天，据估计公共 API 的数量约为 50,000 个。这还不包括数千个私有管理的内部 API，这些 API 在全球主要行业中持续获得采用。根据 SmartBear 2016 年 API 报告，五分之一的 API 提供商在过去五年内才开始开发 API。
随着互联设备数量的指数级增长，API 的采用率只会增加。物联网革命也已到来，家用设备、机器人和可穿戴设备都助长了我们日益增长的保持连接的渴望。到 2020 年，预计世界上每个人平均将拥有七台设备。
这进一步证明了组织应开始考虑其 API 战略，因为 API 是渗透所有这些不同平台和设备的最佳方式。
OAS 驱动开发的简介
API 显然已朝着推动业务增长的方向发展。希望利用 API 的公司需要考虑良好的、由第三方开发人员投入最少精力即可实现的自助服务消费。过去，API 并非供很多人使用。API 是数据驱动的，旨在解决连接和通信的几个特殊用例。文档很少，即使有也很少，所使用的规范直接遵循核心数据库的术语，这意味着除了一小部分人之外，没有人能理解它们。
毋庸置疑，过去的 API 并非为自助服务消费而设计。上述情况不再适用于现代 Web API。新时代的 REST API，与它们的前身不同，不再是数据驱动的，而是更以消费者为导向的。设计良好、能解决实际消费者问题的 API 才是关键，我们从 Dropbox、Stripe 和 eBay 等公司的 API 中看到了这种关注。现在，许多公司都要求基于 HTTP 标准的可重用接口，以实现数据和功能的重用，它们是为消费者需求和自助服务而构建的。
引入 OpenAPI 规范 (OAS)
OpenAPI 规范 (OAS) 对于 REST 而言，就像 WSDL 对于 SOAP 一样。它为设计人员、开发人员、测试人员和运维人员提供了一个构建和维护 API 的通用框架。可以将该规范视为构建和实现 REST API 的一套规则。
OAS 与语言无关，既可供人类阅读，也可供机器读取，这使得人类和计算机都能发现和理解服务的各项功能，而无需访问源代码、额外文档或检查网络流量。例如，它可以直接从 OAS 定义中自动生成交互式、美观的 API 文档。
交互式文档已演变为其自身的专用工具，称为 Swagger UI。Swagger UI 允许开发团队和最终用户可视化并与 API 的资源进行交互，而无需手动将 API 集成和实现到其应用程序中。
将 OAS 添加到您的 API 的好处
- API 设计和协作的合适画布：OAS 为您的团队在开始编码之前协作设计 API 提供了一个单一的焦点。
- 一种清晰且正式的完整重用机制：OAS 定义内部存在明确为通用对象重用和引用而设的机制。它们无需定义编写者解释其含义。
- 自动化的合适工具：OAS 为服务器模板生成（无论是传统型还是无服务器型）提供了正确的结构和工具。除了服务器模板，它还支持以几乎所有流行的客户端语言生成客户端 SDK。
- 测试自动化和监控增强所需的信息：您的质量保证团队可以将 OAS 定义导入其测试解决方案中，从而减少理解 API 操作可能涉及的猜测工作。
OAS 在 API 生命周期中的作用
为了在当今竞争激烈、互联互通的商业环境中取得成功，组织必须对其 API 计划进行一流的处理，使开发人员能够灵活地以他们选择的工作流程与不断发展的内部和外部环境集成。
这就是为什么选择正确的 API 生命周期管理工具变得重要的一个重要原因。对于大多数团队来说，使用 OAS 的 API 生命周期将是这样的
OAS 驱动方法的优势
OAS 驱动的 API 开发倡导在实施任何其他生命周期操作之前，首先设计 API 的定义。这意味着，甚至在您开始构建 API 的业务逻辑、测试 API 是否存在任何错误或缺陷，或执行任何其他生命周期功能之前，您都将设计 API 的接口，详细说明您的 API 端点将展示的确切请求和响应。
OAS 驱动的方法带来了许多与以消费者为中心的 API 开发方法直接相关的巨大优势。
- 更好的开发者体验 (DX)：在竞争异常激烈的 API 生态系统中，良好的 API 消费开发者体验至关重要。您可以事先专注于 API 消费者的需求。这使您能够采用以开发者为中心的方法，并在赶时间和其他开发方面之前，以最佳方式确保满足最终消费者的需求。
- 提升独立性：这种方法减少了处理您的 API 的不同团队（例如前端和后端团队，或架构师、技术文档人员和质量保证团队）之间的依赖性。这是因为 API 的定义使各利益相关者就 API 的预期功能及其与各自工作职能的关系保持一致。它充当 API 预期服务与其功能之间的契约，并确保它们之间更轻松的沟通。
- 更快地推向市场：由于消除了依赖性，不同团队可以以更快的效率执行其功能。团队之间的交接过程明显更容易，从而使您的 API 以更快的速度发布。
- 帮助外部人员理解 API：首先设计 API，这相当于一个强制性功能，可以构建一个易于理解和使用的消费者友好型 API。这也使得您的技术文档团队能够从设计良好的 API 中创建出色的文档。
- 为您的 API 创建测试：您的 OAS 定义提供了一个契约，描述了当有人调用您的 API 时响应的样子。此契约可以重新用于创建测试用例。这可以大幅减少测试您的 API 所需的设置时间。您可以通过导入 API 定义来创建功能测试和负载测试。
- 生成实现代码和 SDK：除了生成文档之外，OpenAPI 定义还可以通过创建实现代码和 SDK 来加速开发。API 定义文件可以导入到 Swagger Codegen 和 SwaggerHub 等多种工具中。这些工具可以用许多不同的语言生成代码，例如 Java、Scala 和 Ruby。
- 使您的 API 上线：Amazon API Gateway、Azure、Apigee 或 Google Cloud 等 API 网关都可以通过 API 定义来创建实时 API。
- 监控您的 API：理想情况下，您希望在客户注意到之前了解您的 API 是否存在问题。如果您将定义导入到 Alertsite 等工具中，API 可以自动受到监控。
对于许多组织而言，完全过渡到 OpenAPI 驱动的方法——也常被称为“设计优先方法”——并非总能一蹴而就。在某些情况下，团队仍遵循“代码优先方法”，即为已构建且可能已部署的现有 API 生成 OAS 定义。代码优先方法是一种更传统的 API 构建形式，在业务需求确定之后才进行代码开发，最终从代码生成文档。
如果开发人员直接从需求文档开始编写 API 代码，他们可以更快地实现 API。如果您的上市策略强调速度和敏捷性是 API 计划成功的关键因素，这一点很重要。代码优先方法中自动化更容易的事实有助于强化这一论点，许多库支持支架式服务器代码、功能测试和部署自动化。有一些开源工具可以利用，通过向您的 API 代码添加注释，在运行时或构建时从现有 API 生成 OAS 定义。
您还可以利用 Swagger Inspector 这样的工具，它可以让您快速执行任何 API 请求，验证其响应并生成相应的 OpenAPI 定义。使用 Swagger Inspector 通过调用每个端点并利用相关响应生成符合 OAS 规范的文档，或者将一系列调用串联起来为多个 API 端点生成完整的 OAS 文档，从而为现有 REST API 快速生成基于 OAS 的文档。
大规模使用 OAS 进行 API 开发
尽管越来越多的组织将设计视为软件开发生命周期及其 API 生命周期中的关键一步，但很少有组织弄清楚如何有效地大规模设计 API。
当您在一个团队中处理数量有限的服务时，设计更容易管理，并且依靠 PDF 样式指南或维基页面可能足以让每个人保持一致。但是，当设计过程需要扩展到多个团队以及数百甚至数千个不同的 API 时，会发生什么呢？
使用 SwaggerHub 优化您的 API 工作流程
团队在实施 API 策略时面临的最大挑战之一是确保具有不同技能组合和职责的团队成员在 API 生命周期的正确阶段参与进来。
其他挑战包括
- 团队管理与协作：您如何跨团队协作更新 OAS 定义，并为您的 API 编写详细文档？
- 版本管理：随着组织不断迭代 API 的设计和文档，管理其 API 多个版本的复杂性也随之而来。组织如何有效地管理同一 API 的多个版本？
- OAS 定义的安全托管与共享：随着您使用 OAS 扩展您的 API 策略，维护一个供团队访问 OAS 定义的中央存储库变得越来越重要。团队如何考虑安全地协调其 API 生命周期的各个方面？
- 与现有工具集同步：如何使您的内部和外部环境与 API 的不同版本保持同步，特别是当您的软件和 API 开发发生在各种外部系统（如源代码控制主机、API 管理平台和测试套件）中时？
应对这些挑战要求组织采用最佳的 API 开发工作流程，并确定必要的工具来优化 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 这样的组织，通过在 API 设计中标准化使用 OpenAPI，并采用一个能够无缝融入其 API 工作流程的工具，从而在 SwaggerHub 中更有效地协作进行 API 设计，成功地扩展了他们的 API 设计。
他们也代表了我们所见到的成功扩展其 API 设计流程的团队的一些关键原则。
准备好扩展您的设计流程了吗？以下是您需要采取的几个重要步骤：
1. 统一团队
良好的 API 设计依赖于 API 开发生命周期中所有利益相关者之间的有效协调。如果您的团队在设计要求上不一致，或者合适的人员无法充分了解设计变更，那么当您尝试超越少量 API 进行扩展时，将会遇到摩擦。组织试图使团队成员在设计过程上保持一致的一种常见方式是通过 Confluence 或 GitHub 等协作工具。
但虽然这些工具在软件开发生命周期中扮演着关键角色，但针对管理 API 设计工作流程的特定用例，它们的配置可能很复杂。
在 SwaggerHub 中，您可以创建组织并邀请团队成员协作设计和文档化您的 API。每个组织可以拥有多个团队，具体取决于他们在 API 生命周期中的角色。组织所有者可以根据团队成员在设计过程中的参与程度，为他们分配角色并管理访问权限。了解更多关于在 SwaggerHub 中协作的信息。
2. 提高设计过程的可见性
正如团队在尝试扩展其 API 设计流程时可能面临的协作挑战一样，提高团队间的可见性也是一项艰巨的任务。通常，我们看到团队会从开源 Swagger 工具（如 Swagger Editor 和 Swagger UI）开始其 API 设计之旅。
尽管这些工具提供了有效建模和可视化 API 所需的功能，但它们并非为促进大型 API 团队的协作需求而构建。如果您使用 OpenAPI 处理 API 设计，您会希望提供一个中央位置，供整个团队访问正在进行的不同服务设计工作。您还需要确保在发生更改时通知到正确的人员，并且您不会将可见性限制在零散的电子邮件、Slack 消息和 GitHub 工单中。
3. 减少依赖
团队间的依赖性是阻碍团队从设计阶段向生成代码、起草文档和编写测试用例迈进的最大因素之一。团队减少依赖性以加速开发的一种方法是通过 API“模拟”或虚拟化。您可以在 SwaggerHub 中创建新 API 时自动创建模拟，也可以随时手动创建。
模拟有助于您在设计 API 时对其进行测试，即在开发人员实现它之前。此外，这种集成使客户端应用程序开发人员甚至在后端准备好之前就可以开始工作。无需编写一行代码，您就可以允许 API 消费者针对模拟开发客户端，模拟保证会以兼容、真实的有效负载进行响应。更重要的是，您可以通过使用“example”构造直接在 OAS 定义中调整有效负载。了解更多关于 SwaggerHub 中的模拟。
4. 设定并强制执行设计要求
一家公司对 API 的投入是一项长期努力。设计标准不仅能改进 API 的实现，还能决定 API 如何更新或新 API 如何开发。一旦设定了设计指南，就更容易在此基础上进行构建，并允许团队开发 API，从而使组织能够扩展其设计和开发流程。由于设计定义了客户端和服务如何交互，因此设计上的差异会导致服务开发阶段的混乱和开销。这些不一致之处只会成倍增加，其影响将在整个 API 生命周期中放大。
SwaggerHub 帮助解决设计一致性问题的一种方法是使用其内置的风格验证器 (Style Validator)，以检查您的 API 定义是否符合某些描述标准。例如，您公司的指南可能要求所有属性都指定示例。风格验证器可以帮助您自动化此类检查。了解更多关于在 SwaggerHub 中标准化设计的信息。
5. 提高设计的可重用性
我们经常从使用 Swagger 工具和 OAS 定义 API 的 API 团队那里听到，在数百个 API 中定义多个端点时，设计过程可能会非常繁琐。需要重复单独定义每一个端点会减慢设计过程，并导致 API 设计中的不一致。
这就是为什么 SwaggerHub 在设计过程中引入了“域 (Domains)”的概念。域是可重用组件，可以在多个 API 和其他域之间共享。一个域可以包含以下组件：定义、路径项、参数、响应。了解更多关于 SwaggerHub 中的设计重用。
6. 与您信任的工具集成
能够快速从设计阶段过渡到 API 的文档化、构建和部署，对于建立可扩展的 API 设计流程至关重要。即使是最好的设计标准，如果您在超越初始阶段时遇到摩擦，也无助于您扩展 API 设计。API 供应商试图解决这个问题的一种方法是在更侧重于 API 管理的工具之上构建额外的设计功能。虽然拥有一个一体化解决方案很棒，但它也要求组织被锁定在单一解决方案中，当您想要引入新工具时，灵活性会大大降低。
在 SwaggerHub 中，我们采取了不同的方法——构建一个世界级的 API 设计平台，供团队用作其 API 设计流程的“事实来源”，然后提供与您的团队信赖的工具的无缝集成，以交付出色的 API，这些工具包括：Apigee、AWS、Microsoft Azure 或 IBM API Connect 等 API 网关；Bitbucket、GitHub 和 GitLab 等源代码控制平台；以及用于功能测试的 SoapUI 等测试工具。
了解更多关于 SwaggerHub API 生命周期集成。
在 SwaggerHub 中优化您的工作流程
SwaggerHub 为各种规模的团队提供灵活的计划。将您所有的 OAS 资产存储在一个中心位置，设置和管理团队，并在 API 的整个生命周期中进行协作。可提供云端版本或通过我们的企业解决方案安装在您的防火墙内。
立即开始！立即开始您的 SwaggerHub 14 天免费试用，或者直接联系团队了解更多关于我们的企业解决方案，您可以在此处安排演示。