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