技术实践标准化规范驱动的API生命周期

　　Lane：我想与您分享一下API规范为何重要的高级观点。OpenAPI、AsyncAPI、JSONSchema等如何帮助我们以机器理解的方式标准化和交付API生命周期。此外，还让我们人类能够在API生命周期中更好地沟通、协作和前进。
　　我的名字是金莱恩。我是Postman的首席布道者。我领导我们的开放技术团队，其中包括我们的DevRel、我们的API生命周期组，还投资于API规范，如OpenAPI、AsyncAPI和JSONSchema，以及围绕它们的工具。API规范对我和Postman都非常重要。我想分享一点关于我们如何看待API规范影响我们生产和使用API的方式。
　　API规范并不新鲜
　　API规范并不是什么新鲜事。在过去的20年里，WSDL一直在定义Web服务。随着更多基于Web的API方法出现，我们也看到了WADL的发展，以帮助我们描述API的表面区域。真的，直到Swagger在2010年和11年问世，才帮助我们使我们的文档更具交互性，更加实用。帮助开发人员了解API的作用以及如何使用它，我们才真正开始看到API规范的好处。到2015年，Swagger已经成长起来。这是第二版。它被放入Linux基金会，创建了OpenAPIInitiative以推进规范，并将其重新命名为OpenAPI。帮助我们描述过去五六年的HTTPAPI和webhook。为我们如何定义、设计、交付、部署和弃用API提供基石。
　　开放API
　　让我们看看OpenAPI。OpenAPI允许我们描述同步API的表面区域、描述信息、API的功能、您可以在哪里找到它、服务器。更重要的是，每个响应的各个路径、参数和详细信息，包括被解析为请求主体或作为每个响应的一部分返回的模式。OpenAPI为我们提供了一种机器可读的JSON或YAML方式来描述我们的API是什么，HTTP1。1API的作用，并允许开发人员在API生命周期的不同点使用该规范。异步API
　　AsyncAPI允许我们描述异步API的表面区域，建立在OpenAPI给我们的基础之上，但允许我们描述通道、消息以及绑定。跨TCP、MQTT、AMQP执行发布和订阅API。允许我们定义这些API如何跨多个协议工作，并定义哪些模式用作有效负载的一部分，用于发布和订阅哪些消息来回发送到这些异步API。OpenAPI和AsyncAPI都允许我们描述当今工具箱中的大多数API。
　　JSON模式
　　JSONSchema允许我们描述和验证这些API的有效负载。为我们提供了一种机器可读的方式来描述对象、它们的属性、它们包含的数据类型以及实际需要什么，以便我们可以验证这些对象。JSONSchema用于多个OpenAPI以及AsyncAPI。他们有自己的JSONSchema词汇表，允许他们在OpenAPI的情况下描述和验证请求和响应负载。AsyncAPI上下文中的发布和订阅有效负载。提供一种机器可读的方式，允许我们描述我们的API正在做什么。来回解析哪些资源，然后在这些非常抽象的API中封装了哪些功能，这些API通常很难查看和验证。API规范为API生命周期提供动力
　　API规范用于为API生命周期中的多个站点提供支持。最值得注意的是，它用于文档。许多使用Swagger的人认为Swagger是文档。实际上，Swagger是一种规范，您可以使用它来生成文档。Swagger、OpenAPI和AsyncAPI用于描述每个API的技术细节。然后允许我们发布文档。允许我们始终保持我们的文档是最新的，通过使用该API规范使用开源或商业选项生成文档，跨团队交付一致的文档。API规范也用于生成模拟服务器。这些模拟服务器可以是API设计优先方法的一部分。设计它并模拟它，这样你就可以确保它做它需要做的事情。它可以用作QA和测试的一部分。然后，一些小组将它用于生产环境中的沙箱，因此开发人员在学习API的作用时实际上不必处理生产数据。API规范也被用作测试的脚手架。允许API生产者生成合同、集成、性能和其他类型的测试，以帮助他们确保API正在做它应该做的事情，将这些测试作为管道的一部分运行或使用监视器安排它们。
　　相同的方法可用于安全性。您可以使用OpenAPI规范或异步扫描API的表面区域以查找漏洞，审核身份验证。使用OWASPTop10检查其他常见漏洞，尝试了解您的API是否安全，因为它们应该在团队之间保持一致。API规范支持生命周期的另一种常见方式是通过代码生成。许多公司正在使用OpenAPI和AsyncAPI来生成客户端或服务器端代码，因此您实际上可以使用规范来生成代码，以便您部署API、将其部署到网关或生成各种编程语言的SDK。允许公司生产SDK，各种编程语言的库和代码片段，而无需在团队中具备这些编程语言技能。这真的是一个重要的看为什么规格很重要。它不仅适用于文档，还适用于整个生命周期。API的一个规范可用于生成文档、模拟、测试、保护该API，然后生成您将使用的代码来实际将该API变为现实或将其用于集成或应用程序中。将API规范变为现实的多种方法
　　您可以通过多种方式将API规范变为现实。最值得注意和最近的方法之一是通过设计优先的方法。你从一个OpenAPI或AsyncAPI开始，生成一个模板，然后手工设计它，确保它完全符合你的需要。然后生成一个模拟服务器并发布文档，以便其他利益相关者、其他团队成员可以使用它并就该API提供反馈，允许您在实际编写代码之前设计API、模拟它并记录它。然后，一旦您对它进行了足够的迭代，您就可以将其作为API发布。
　　生成API规范的第二种常见方式是代码优先。团队开始编写代码，做他们最擅长的事情。然后，在编写代码时，您可以对其进行注释，或者使用网关或代理。您可以从代码生成OpenAPI和AsyncAPI。你先编码。您生成OpenAPI或AsyncAPI，然后可用于生成文档测试并帮助保护您的API。另一种常见的方法是对Web或移动应用程序进行逆向工程，并为已在生产中、已在应用程序中使用的API生成OpenAPI或AsyncAPI。然后，只需要发布文档并保持最新。生成测试并保护该API，允许将现有API引入更标准化的API生命周期，并与其他设计或代码优先的API一起使用。行业标准使用规范
　　API规范在行业标准中发挥着关键作用，尤其是PSD2。您可以在欧盟之外找到适用于PSD2标准的OpenAPI，该标准用于管理和规范金融和支付API的部署和发展方式。您可以看到OpenAPI被用于火灾规范，定义了API在医疗保健领域的交付方式。提供每个请求和响应的所有技术细节，帮助提高医疗保健的互操作性。OpenReferral是另一个API标准，它使用OpenAPI为市政、市级、县级卫生和公共服务提供定义，使城市可以更轻松地跨州和跨国家共享数据。另一个是OpenTravel，它塑造了我们在旅游业中交付API的方式，与航空公司合作，招待活动和其他事情。提供可用于部署旅行API的通用标准集，使行业更具互操作性。另一个例子是地理空间联盟。他们正在制定地理API标准，您可以找到他们API的OpenAPI规范。这只是一个快照。还有很多其他标准，包括汽车行业和保险。在API产生影响的大多数行业中，您都可以找到OpenAPI，并且越来越多地使用AsyncAPI来定义该领域。s许多其他标准，包括汽车行业和保险。在API产生影响的大多数行业中，您都可以找到OpenAPI，并且越来越多地使用AsyncAPI来定义该领域。s许多其他标准，包括汽车行业和保险。在API产生影响的大多数行业中，您都可以找到OpenAPI，并且越来越多地使用AsyncAPI来定义该领域。
　　规范提供治理框架
　　OpenAPI、AsyncAPI和JSONSchema到位后，为我们提供了实现跨大型企业组织治理的框架。OpenAPI和AsyncAPI为我们提供了设置设计指南的能力。应该如何描述我们的路径？什么参数？他们应该是骆驼案还是蛇案？架构应该是什么样的？模式如何演变以最小化破坏性更改？所有这些设计指南都可以以机器可读的方式编码并应用于OpenAPI和AsyncAPI。整理规则。lint描述API的OpenAPI或AsyncAPI是很常见的，因此您可以验证它是否具有特定的结构和形式。这就是linting为我们提供的。我们可以定义构成我们的设计指南和整体企业治理的规则。我们可以将这些规则应用于我们的API合约已定义。然后我们可以使用合同测试来应用它，这样我们就可以验证这些规则是否在设计时、开发时以及构建时得到应用。
　　这些规范使我们能够掌握变更管理。这些对象由模式定义。这些由OpenAPI和AsyncAPI定义的提供对这些对象的访问的API将随着时间而改变。OpenAPI、AsyncAPI和JSONSchema允许我们量化这种变化。对此应用基于语义日期或其他类型的版本控制，并掌握这些资源和功能如何发展。然后我们可以自动化所有这些。在编辑OpenAPI、Async或JSONSchema时，我们可以将其自动化，以便在设计工具中获得实时反馈。您可以在IDE或命令行中的管道或开发时应用，并允许在整个API生命周期和跨开发团队中实现治理，帮助他们自动化应用治理的方式。然后一路学习，
　　API规范是我们作为一个团队一起工作的方式，因此您可以在文档中看到这些证据。为什么SwaggerUI和Redoc以及规范驱动的文档变得如此重要。这就是我们API生产者与API消费者沟通的方式。这些规范随着它们的发展和在整个API生命周期中的应用，为协作开辟了机会。我们现在可以共享工件。当我说API分页时，我可以分享我的意思。这是它的规范。当我说这是一个图像对象时，我可以分享我的意思。我可以为此分享JSONSchema。围绕这些工件的共享和协作使我们能够更紧密地合作，并在这些结构中具有相同的含义。然后因为我们可以使用现有的源代码控制来烘焙它，所以我们拥有这些工件。
　　我们的OpenAPI和AsyncAPI位于设计它们的工作区中。它们存在于GitHub、GitLab和Bitbucket存储库中，代码在这些存储库中被提交，并被跨基础设施使用，以使用这些API进行部署和自动化。所有这一切使我们能够跨团队进行标准化，因此我们可以更好地沟通、协作、共享，并且我们拥有这些工件，可以帮助我们理解谈论这些非常抽象的API概念时的含义。它可以帮助我们达成一致，标准化我们做事的方式，然后通过源代码控制实现自动化。这可以在团队级别、组织级别完成，也可以在行业级别使用标准，使API在其整个生命周期中更加一致和迭代。规范是我们业务运营的语言
　　当这些OpenAPI成熟时，它们为我们提供了定义我们操作的不同领域的能力。这就是我们如何区分不同的业务线、我们用来运营的不同领域的方式。它可以很好地描述和定义我们的团队是如何组成的。我们如何组织我们的团队，以及他们如何在这些不同的业务线和团队中工作。OpenAPI、AsyncAPI和JSONSchema以及它们之间的标记，使我们能够在这些不同的领域中划分我们所有的资源和数字能力，描述我们拥有的不同资源。不同的图像、视频、人物和地址，我们拥有的所有不同的数字资源，以及跨这些资源采取的能力、算法和行动。在OpenAPI中描述所有这些，标记事物，帮助我们建立和形式化我们描述它的词汇。我们使用这些模式作为请求的一部分发布到API，在事件驱动的API世界中作为响应返回、发布、订阅。我们正在标准化我们如何描述这些对象，我们如何谈论它们。我们正在减少这些资源和功能的冗余，为我们的运营方式创建更多的逻辑域。确保它尽可能高效且定义明确。然后领域专家可以真正帮助指导和管理我们业务运营的这一部分。重新标准化我们如何描述这些对象，我们如何谈论它们。我们正在减少这些资源和功能的冗余，为我们的运营方式创建更多的逻辑域。确保它尽可能高效且定义明确。然后领域专家可以真正帮助指导和管理我们业务运营的这一部分。重新标准化我们如何描述这些对象，我们如何谈论它们。我们正在减少这些资源和功能的冗余，为我们的运营方式创建更多的逻辑域。确保它尽可能高效且定义明确。然后领域专家可以真正帮助指导和管理我们业务运营的这一部分。规格适用于人和机器
　　规范适用于人和机器。尽管它们是用JSON或YAML编写的，并且非常机器可读且结构化，因此它们可以导入到不同的服务和工具中。它们可以用作源代码控制的一部分。API生命周期可以通过这种方式实现自动化。它们也非常适合人类。我们使用它们非常重要。迭代它们。记录它们，并让人们可以在他们的工作中使用它们。规范通常被视为一种开发工具。它们越来越多地被项目和工程经理、API设计师和架构师用来塑造整个企业组织的领域，并用作进行设计审查、安全审查和其他方式的一种方式。将其用作工件来指导与实际构建API和在其之上的应用程序的开发人员的对话。重要的是要使规范保持最新，因为人类依赖于此。这些规范正在帮助我们解决我们在整个组织中遇到的许多人为挑战和摩擦。提升它、缩小它并将规范视为文档或代码生成或只是某个服务器上某处的JSON工件，这一点很重要。这在很大程度上是人类用来推进我们的运营并取得成功的合同。这些规范正在帮助我们解决我们在整个组织中遇到的许多人为挑战和摩擦。提升它、缩小它并将规范视为文档或代码生成或只是某个服务器上某处的JSON工件，这一点很重要。这在很大程度上是人类用来推进我们的运营并取得成功的合同。这些规范正在帮助我们解决我们在整个组织中遇到的许多人为挑战和摩擦。提升它、缩小它并将规范视为文档或代码生成或只是某个服务器上某处的JSON工件，这一点很重要。这在很大程度上是人类用来推进我们的运营并取得成功的合同。标准化、规范驱动的API生命周期
　　标准化的API生命周期意味着我们将所有这些资源和功能定义为机器可读的工件。我们不仅仅关注HTTP1。1、REST或现有的API部署方式。我们有一个多样化的工件工具箱，允许我们描述事件驱动和消息驱动、GraphQL、gRPC、Kafka、NATS。我们能够使用一整套API解决方案来帮助我们描述、定义、交付和操作这些API，从而使生产者和消费者都受益。这有助于我们标准化我们定义和设计API的方式。我们如何交付。我们是如何在跨团队、跨组织的情况下大规模开展这项工作的。当你去一个大型企业集团，你去让一个API工作时，它具有相同的特性。它具有相同的属性、参数。它具有一致的文档。它有我需要的代码库，并且它们使用与我正在使用的编程语言相匹配的约定。
　　所有这些都是由这些API规范驱动的。OpenAPI和AsyncAPI被用作这方面的护栏。它们正在与合作伙伴和第三方消费者一起发布到组织内部或外部的中央目录。这些OpenAPI、AsyncAPI和JSONSchema可用于任何服务或工具。API生产者拥有更流畅、高速、高效、敏捷和灵活的方式来交付API，能够响应变化并将其API发布出去。这些API的消费者可以访问这些相同的合约，因此他们知道事情何时发生变化。他们能够围绕这些API自动化、构建和集成，而无需阅读文档。他们可以只导入一个OpenAPI。他们可以导入AsyncAPI。他们可以使用JSONSchema来验证和测试。然后他们可以获取API生产者围绕这些规范构建的所有工具，并将它们投入使用。
　　标准化的规范驱动的API生命周期是您在过去十年中使用公共API或在过去五六年大量投资于微服务的大多数企业组织中看到的。您会看到他们确实在努力掌握在整个企业组织中使用OpenAPI的方法。采用和学习如何使用AsyncAPI。然后使用JSONSchema来处理正在解析的内部数据、模式、工件。这是组织、架构师和一些更先进的前倾公司的领导层采用这些API规范的第一要务。围绕它们进行标准化。然后，在众所周知的API生命周期中应用它。概括
　　我知道很多人在谈到API时都陷入了困境，只关注文档或代码生成，或者围绕这些OpenAPI进行设计和架构。希望这可以缩小并展示OpenAPI、AsyncAPI和JSONSchema是如何协同工作的。更重要的是，它们如何在一致的API生命周期中应用。因为一旦您可以通过这种方式在整个生命周期内对其进行标准化和稳定化，您将开始看到在运营速度、性能、质量和正在发生的事情的整体治理方面所带来的好处。我建议转到OpenAPI、AsyncAPI或JSONSchema，这三种开源解决方案都可以让您描述您将如何使用API。这些社区中的每一个都可以作为您运营的一部分，从中学习并投入工作。问题和解答
　　Betts：规范是针对人和机器的，似乎是一个反复出现的主题。主题演讲是关于程序员的大脑以及阅读和理解代码所需的内容。稍后还有另一场谈话谈到了可读性因素，即代码需要可读。你能更深入地了解它的可读性吗？因为我看到了YAML，而且我认为这不是人类可读的。它可能是程序员可读的。是什么使它具有人类可读性？
　　Lane：YAML是一个开始。当从JSON切换到YAML时，我已经看到业务利益相关者会更多地参与其中，令人惊讶的是，括号、逗号和引号的消失会起到什么作用。我同意。它仍然适用于程序员。如何使其更具可读性是使它们的范围更小。与其创建大型的单体API，不如创建更小的微服务和更小的基于产品的API，这些API更易于理解它们在范围内的作用。然后，您遵循领域驱动设计，并进行事件风暴。你真的会在语言中找到尽可能有意义和有目的的词汇。API的设计很直观。它与域对话。它与业务对话中的利益相关者交谈。所有这些都将为此做出贡献。不是拉丁语或希腊语，当它在YAML中时尝试阅读它，这是我们习惯的熟悉词汇。它的范围很简单，而且对人们来说更容易消化。所有这些设计工作确实有助于实现这一点。我同意，我们还有很长的路要走，OpenAPI或JSONSchema仍然比它应该的技术要多一些。
　　Betts：工具是否到位，您可以生成更易于阅读的文档？就是这样，使用YAML，使用JSONSchema来组织常用词，然后有人会阅读你的Swagger页面，不管它是什么。
　　Lane：我是第一个承认，真正的OpenAPI、AsyncAPI，它们只是我们正在寻找的任何其他结果的配置文件。真的，我们人类不应该那么在意它。我们应该能够点击查看源代码。我们应该能够访问配置文件。确实，最终结果是我们应该得到的结果。这取决于工具和服务提供商来帮助我们实现目标。在那之前，我们需要稍微提升这些规范，吸引更多的眼球，让更多的人使用它们，这样工具才能让我们到达那里。
　　Betts：既然你提到了DDD，我就想问这个问题，因为DDD有泛在语言的概念。它是有界上下文中无处不在的语言。在这里，您正在谈论您的API，即外部接口。它仍然是一种无处不在的语言，但它处于不同的层次。有不同的人参与吗？是业务利益相关者，而不是开发团队与他们的技术产品经理一起工作吗？
　　Lane：是的，非常多，这取决于您正在构建的API和服务的范围。OpenAPI，无论是更多产品、面向外部的API，还是微服务。无论您有事件驱动的微服务，还是使用更异步的Kafka将它们连接在一起，这种方法，一种事件驱动的方法。您的域对话将根据您要完成的任务而形成。只是内部吗？只是私人的吗？是和合作伙伴一起吗？是行业焦点吗？您的领域将非常受这些目标和目标的限制。它因景观而异。真的，这是你应该做的领域驱动的设计练习，是充实的。我们的域名是什么？什么是有界上下文？我们的界面应该是什么样的？我们所有的对象应该是什么？重新解析？他们协同工作。仅仅基于它是内部的、合作伙伴的、私人的，你的观众是谁，真的会定义很多。
　　Betts：这些规范讨论了请求响应、输入以及立即返回的输出，但它并没有提供稍后发生的内容那么深入。有这方面的例子吗？当我将此请求发送到我的API时，是否有关于触发哪些事件的规范？因为那时您可以记录所有规范。
　　莱恩：是的。AsyncAPI具有事件驱动发布和订阅的概念。两者之间有一个维恩图重叠。我不会说它应该是连贯和清晰的。比如说，我正在使用一个常规的API来发出请求和响应，我如何了解webhook以便获得推送？在我提出请求后，我得到了回复，我收到了回复，但之后还会发生一些其他事情。在OpenAPI中，您可以说有链接对象，这就是下一步。这就是接下来的事情。我相信你甚至可以说，如果你想订阅这个，这里有一个WebSockets标头，它会指向一个WebSockets来实际订阅它。我见过几个在HTTP和TCP之间进行切换的比特币API，即WebSockets。至于您如何在OpenAPI和AsyncAPI中描述请求和响应以及事件驱动世界之间的关系，它并不像应有的那样顺畅。我看到很多人都在努力让它变得更有意义。
　　Betts：其他问题之一是关于分页、扩展、国际化等公共部分的子规范？您能否在两个文件之间进行链接，以便每个人都不必重复在您的所有服务中通用的相同标志定义？
　　莱恩：是的，重复使用。在OpenAPI、JSONSchema和AsyncAPI中，您可以引用，所以有一个美元符号ref。OpenAPI3非常注重重用。它有一个组件库，您可以在其中放置参数和放置东西，然后只需在文档中引用它们。您也可以在OpenAPI之外执行此操作。您可以拥有一个OpenAPI，就像您的所有公共部分、您的分页、您的请求正文以及您重用的所有东西一样。然后，您可以在OpenAPI中引用具有完整URL的那些，并重用它们。这个概念存在于所有三个规格中。问题在于对此的工具支持，因为工具支持并不像应有的那样健壮和一致。这是我们真正正在努力的事情，因为那里有很多很棒的模式，很多很棒的可重用模式我们可以投入使用。帮助你做到这一点的工具，你必须知道如何做到这一点，并且成为一个手工编辑你的OpenAPI的铁杆，而不是在这些日子里依赖工具来做到这一点。我们将在未来一两年内解决这个问题。
　　Betts：在同样的轨迹上，您提到Swagger大约在10年前，但后来成为OpenAPI，成为Linux基金会的一部分，2015年。AsyncAPI延迟了几年。它今年刚刚进入Linux基金会。它刚刚达到第二版。是不是同样的事情，只是退后几年？我们是否可以期待类似的情况，需要几年时间才能到达那里，还是会更快地增长？
　　莱恩：我认为它会增长得更快。当谈到Swagger时，我觉得我们非常像2012年，比如工具的数量，它周围空间的能量。我们在AsyncAPI方面也处于同一点，但由于核心工具的存在，我们将更快地到达那里。OpenAPIInitiative不管理任何工具。它仅将规范作为Linux基金会的一部分进行管理。当TonyTam创建Swagger并运行Swagger时，他有SwaggerUI。他有Swagger代码生成器。他有核心工具。在2。0版本中，正是这种共生关系让Swagger得以迅速发展。我们在3。0中遇到了麻烦。核心工具以及解析器、生成器、文档、代码生成和规范之间的关系至关重要。这就是AsyncAPI会爆炸的原因。已经爆了
　　Betts：这类似于你的API开始被使用，你必须担心向后兼容性。你必须让更多的人开心并做出更多的决定，并且随着你的发展可能会慢一点，这样你就可以实现下一个伟大的事情。
　　莱恩：你必须更周到。
　　Betts：所有这些资源都可以创建这个非常多样化的工具箱。您提到了REST、gRPC和GraphQL。这些工具适用于所有技术堆栈，但它们是否成熟，或者REST、JSON比gRPC和GraphQL更进一步？
　　莱恩：我们正在达到成熟点。GraphQL和gRPC在企业工具箱中都非常成熟，被广泛采用。社区范围没有那么大，从讲故事的角度来看，你在空间中听到的内容并不完全有信心。在那里。在那里，毫无疑问，我看到很多涉及这两者的企业采用。我看到了整个光谱。我将带有GraphQL的WebSockets视为发布和订阅，这是一个有趣的混合体。然后使用gRPC，我看到在JSONSchema和其他东西的序列化方面有很多二进制投资。它们正在达到成熟点，并且开始影响范围的其余部分，但REST有一个巨大的领先优势。