跳至主要内容
类别

博客

总部位于丹佛的 Cloud Elements 加入 Open API Initiative 成为最新成员

作者: 博客

Open API Initiative 很高兴地欢迎 Cloud Elements 加入 OAI,Cloud Elements 是一家总部位于科罗拉多州丹佛的统一 API 集成和管理平台。以下是我们最新成员关于加入 OAI 的益处以及他们为何为 OpenAPI 规范做出贡献的看法。

Mark Greene, CEO of Cloud Elements

Cloud Elements 首席执行官 Mark Greene

首席执行官兼联合创始人 Mark Geene 分享道:“我们很高兴成为 OAI 的最新成员,加入到创建、发展和推广供应商中立 API 规范的队伍中。从早期开始,Cloud Elements 就认识到开放、机器可读的 API 文档的重要性,并且一直致力于 Swagger。”

The Cloud Elements Summer Hike Days at Matthew Winters near Red Rocks.

Cloud Elements 在红岩附近的 Matthew Winters 举办夏季徒步活动。

加入 OAI 是我们 Cloud Elements 产品开发战略中不可或缺的一部分,我们相信这将进一步增强我们 API 集成平台的简单性,并继续减轻客户将 Cloud Elements 与其他 API 管理平台和 API 网关相结合的负担。最终,我们相信 Open API Initiative 不仅为我们自己的开发人员节省了大量时间,也为我们的客户的开发人员节省了时间。

根据规范构建 API 是成功的关键。我们的高级平台工程师 Rocky Madden 补充道:“Open API Initiative 不仅采用了 Swagger 规范,而且还在 v3.0 版本中提升了自身水平,改进了 API 如何被人类和机器发现和理解的方式。互操作性是 OAI 的核心。当工具和服务能够围绕相同的通用规范构建时,它非常强大,使我们能够创建强大的集成,改进我们与其他 API 的互操作性,缩短交付时间等等。”

Rocky Madden, Senior Software and DevOps Engineer, Cloud Elements

Rocky Madden,
Cloud Elements 高级软件和 DevOps 工程师

Madden 继续说道:“对我们而言,OpenAPI 规范改进了我们自己的平台,并帮助我们快速将新的元素(端点)添加到我们的集成目录中。标准化也使我们能够利用其他也基于 OAI 构建的云服务。我们与亚马逊 AWS 等公司的合作将允许开发人员创建可以轻松发布到此类市场中的 REST API,这在一定程度上得益于与 Open API Initiative 的合作。”

包括我们自己在内的许多公司都加入了支持 Open API Initiative 的运动。我们非常高兴能成为 OAI 的一部分,并继续创建和发展 API 描述格式。

TDC:文档,解释 3.0 规范第 5 部分

作者: 博客

随着 OpenAPI 规范 3.0 版本即将进入候选 Beta 版本,这一系列文章旨在从技术开发人员社区 (TDC) 的角度提供对变化内容和方式的见解。本系列早期的文章描述了规范下一步演变的背景和基本原理,一些结构变化请求参数以及协议和有效负载

文档

围绕 OpenAPI 规范先前版本发展起来的各种工具表明,这些开发人员能够访问构建这些工具所需的信息。3.0 版本不仅应该延续这种成功,而且随着 TDC 和社区成员参与度的提高,规范应该比以前更容易访问、更清晰、更明确。

目录

openapispec_tableofcontents
Rob Dolin在规范中添加了一个目录,以便为新读者提供文档结构的快速概述,并且它将使访问规范参考的相关部分变得更容易。随着规范更改开始稳定下来,文档工作将加快步伐,规范将变得更容易访问。

通用标记

2.0 规范使用 GitHub Flavored Markdown (GFM) 来提供服务的丰富文本描述。不幸的是,GFM 本身没有正式规范,其某些功能仅适用于托管在 GitHub 上的内容。出于这个原因,OpenAPI 规范 3.0 草案采用了 CommonMark 格式,这将使工具在渲染 Markdown 时更加一致。CommonMark 大部分与 GFM 兼容,因此此更改对现有文档几乎没有缺点或影响。并且,由于 CommonMark 带来了详细的规范,因此提高的精确度将减少歧义,并且总体上应该是一个福音。

下一篇文章将讨论社区提出的其他各种未决问题。


Darrell Miller关于作者

Darrel Miller 是 Microsoft Azure API Management 的高级软件开发工程师。Darrel 是 OpenAPI 规范技术开发人员社区的成员。您可以在 Twitter 或他的博客 Bizcoder 上关注他。

TDC:协议和有效负载,解释 3.0 规范第 4 部分

作者: 博客

随着 OpenAPI 规范 3.0 版本即将进入候选 Beta 版本,这一系列文章旨在从技术开发人员社区 (TDC) 的角度提供对变化内容和方式的见解。第一篇文章描述了规范下一步演变的背景和基本原理,第二篇文章介绍了结构变化,第三篇文章讨论了请求参数

协议和有效负载

OpenAPI 规范在描述标准请求/响应 HTTP API 方面取得了巨大的成功。但是,社区中的许多人表达了对描述超出简单 HTTP 模型的分布式 API 的兴趣,例如 WebSockets API、RPC API、超媒体 API 和发布/订阅 API。经过 TDC 的大量讨论,目标是将规范扩展到其中一些新的用例,而不会对现有用例增加明显的复杂性。

回调

Webhook 利用 HTTP 以发布/订阅模式工作,并且已成为 API 提供商中的一种流行模式,包括 Slack、GitHub 和许多其他流行的服务。Webhook 使用简单,并且很好地适合现有的基于 HTTP 的 API 风格。但是,对 OpenAPI 规范的一个批评是它无法描述出站 HTTP 请求及其预期的响应。新的回调对象使这成为可能。一个回调对象可以附加到订阅操作,以便描述订阅者可能期望的出站操作。

Path Item Out Going

链接

许多描述超媒体 API 的方法已提议到 GitHub 上的 OpenAPI 存储库。一个主要问题是,超媒体 API 中资源的静态描述与超媒体 API 的运行时/发现哲学优势相矛盾。尽管如此,描述 API 中资源之间静态关系的能力仍然具有一定的优势。为此,3.0 草案规范引入了链接对象,以便描述根据从初始资源检索到的信息可以访问哪些新资源。这并不一定是超媒体驱动的,因为新资源的 URL 没有嵌入到返回的有效负载中,但它们是根据 OpenAPI 规范中定义的规则构建的。已引入了一种新的表达式语法,以允许来自响应的信息与链接操作中的参数相关联。

Path Item Link Object

资源之间链接的静态描述应该能够生成更有用的文档和客户端库,这些库可以封装从一个资源遍历到另一个资源的过程。这可以允许客户端库减少客户端应用程序和服务器定义的资源层次结构之间的耦合。

JSON Schema

许多请求要求扩展 OpenAPI 规范允许的 JSON Schema 子集,以包含 JSON Schema 的更多复杂特性。在 2.0 规范流程中,围绕代码生成的潜在工具复杂性促使排除了 anyOf 和 oneOf。但是,许多用户要求放宽该限制,即使这会影响对这些特性的工具支持。这是规范设计中的一大挑战,在做出此类选择时,永远不容易知道是提供人们可能用其自残的锋利工具更好,还是依靠经验说“不”,这种责任的负担太大了。虽然 OpenAPI 2.0 采用了更保守的方法,但用户群已经变得更有经验,因此一些限制正在被解除,用户将不得不做出明智的选择。

替代 Schema

随着对非 JSON 媒体类型支持的改进,仅使用 JSON Schema 来描述有效负载的局限性变得越来越难以维持。TDC 目前正在探索如何启用描述非 JSON 有效负载的 Schema 的选项。如果可以克服这一挑战,则可能可以完全删除表单参数类型,并支持像 gRPC 这样使用 protobuf 和 protobuf Schema 的协议。

下一篇文章将讨论一些计划对文档进行的改进。


Darrell Miller关于作者

Darrel Miller 是 Microsoft Azure API Management 的高级软件开发工程师。Darrel 是 OpenAPI 规范技术开发人员社区的成员。您可以在 Twitter 或他的博客 Bizcoder 上关注他。

OpenAPI 规范在 APISTRAT 2016 上

作者: 博客

OpenAPI Initiative (OAI) 致力于创建、发展和推广基于 Swagger 规范的供应商中立的 API 描述格式。作为 Linux 基金会下的一个开源项目,OAI 致力于开发和推广 OpenAPI 规范供所有人使用。我们欢迎来自成员和非成员的贡献。

您和您的组织可以做很多事情来帮助社区。

  1. 利用规范:使用 OpenAPI 规范无需支付任何费用或会员资格要求:GitHub | OpenAPI 规范
  2. 开发规范:欢迎社区所有成员参与关于如何发展规范的讨论。找到一个适用于您项目的元问题。如果您没有看到此处的任何问题,请记录一个新的问题
  3. 分享您如何使用规范。
    • 关注我们的 Twitter:@OpenApiSpec
    • 加入我们的 LinkedIn 群组:OpenAPI 规范
    • 参加您所在地区的Meetup,或提供在 Meetup 上进行演示。
    • 当然,也可以在您自己的博客上分享。
  4. 如果您希望直接支持该项目,请考虑让您的公司加入 OAI 成为成员。填写此表单以了解更多信息。项目章程在此

不确定如何开始?阅读如何参与此处


在 APISTRAT 2016 上了解更多信息

11月3日

API 设计与治理 | 上午 11:00 – 下午 12:30
Matthew Reinbold,Capital One DevExchange API 卓越中心负责人
当一家公司决定将所有内容都变成 API 时会发生什么?组织可能会快速效仿 Netflix 和 Amazon,追求微服务和面向服务的架构 (SOA)。但是,如果没有应用 Conway 定律,任何治理工作(以及由此产生的 API 程序)都将达不到预期。Matthew 在多个企业公司建立和发展 API 治理程序方面发挥了重要作用。在本演讲中,他将讨论有效的 API 治理以及实现它的挑战。

微服务:gRPC 或 REST?为什么不两者兼而有之? | 上午 11:00 – 下午 12:30
Sandeep Dinesh,Google Cloud 开发者布道师
在本演讲中,Google 的 Sandeep Dinesh 将向您展示如何构建一个 gRPC 端点,该端点可以在同一端口上智能地通过 HTTP/2 提供 gRPC 服务,同时通过 HTTP/1.1 提供 JSON/REST 服务!然后,他将介绍一些基准测试和最佳实践,用于以可扩展的方式部署这些微服务。在此处阅读更多信息

超媒体

超媒体与图:最佳搭档还是下一场 API 战场? | 下午 1:30 – 下午 3:00
Gareth Jones,微软
我们都在想,今年是否会是超媒体成为主流的一年?但是,在发展的轨道上,出现了一个新的挑战者:图形形状的 API 预先定义了广泛的关系网络,承诺了一些超媒体 API 的优势,但提供了一种更熟悉的编程模型。在超媒体甚至还没有机会之前,图是否会将其推到一边,或者这两种风格是否会和谐相处?这一趋势是通往 HATEOS 涅槃的障碍还是垫脚石?
我将挑战听众考虑将这两种方法结合起来,为主流超媒体的使用打开大门,用动态数据和行为丰富固定的图形。易变的数据和逻辑可以使用超媒体,而更基础的数据可以使用图形方法。通过这种方式,我们可以为我们的应用程序添加价值和深度,而无需像我们经常期望的那样从过渡到超媒体进行彻底的重写。在此处阅读更多信息

 

企业
为遗留 SOAP 服务注入新的活力 | 下午 3:05 – 下午 4:35

Darrel Miller,微软软件开发人员
现实情况是,SOAP 服务不再酷了。如今的开发人员希望与标有 REST 的 API 集成。他们想要描述性的 URL、JSON 有效负载和熟悉的 HTTP 状态代码。但是,许多企业花了 10 年时间构建 SOAP 服务,并且其中许多服务今天仍在正常运行。重写它们将是一项巨大的工作,而收益却可能微乎其微。好消息是,无需重写即可为开发人员提供他们想要的东西。您可以利用 HTTP 的分层架构在 SOAP 服务前面放置一个外观,重用所有现有的代码,为您的服务注入新的活力,并且仍然支持愉快地发送 SOAP 消息的现有客户端应用程序。本次演讲将探讨将本地 HTTP 请求转换为 SOAP 消息并转换回本地 HTTP 响应的过程。我们将讨论外观过程的哪些部分可以自动化,哪些部分需要设计决策。最后,我们将探讨使用这种新的 API 风格可以获得哪些功能以及会失去哪些功能,以便您可以对 SOAP 服务的未来做出明智的决策。

大图景中的大问题 | 下午 3:05 – 下午 4:35
Amber Fallon,SmartBear 软件
API 非常庞大。比我们许多人,甚至包括我们行业中的一些人所意识到的还要庞大——事实上,公开 API 的总数已从 2012 年的不到 7500 个激增到 2015 年的超过 15000 个。大型公司拥有更大的 API 结构,其依赖项和集成比以往任何时候都多,而且这个数字还在不断增长。围绕一些行业巨头提供的 API 已经形成了完整的商业模式。想象一下,像 Uber 或 Waze 这样的应用程序巨头在没有 Google 地图技术的情况下如何运作,或者 Netflix 与为其视频流提供动力的底层应用程序之间重要的关系——这些应用程序绝对依赖于其底层的 API。而且,每天都会出现依赖于公开 API 的新应用程序。
随着这种规模的扩大,随之而来的是一些挑战,例如以促进依赖 API 增长、扩展、维护 SLA 以及允许用户创建应用程序的多功能性的方式管理您的公开 API;您的 API 可能以您从未设想的方式使用。在本课程中,我将解决诸如大规模沙盒、辅助最终用户集成以及管理大型 API 可能遇到的无限数量的依赖项等挑战。

您可以降低到多低?使用 AWS Lambda、API Gateway、Elastic Beanstalk 和 3scale 降低成本和开发时间(别忘了 Swagger!) | 上午 9:05 – 上午 9:30
Erin McKean,Wordnik 创始人
超过 18000 名开发人员拥有 Wordnik API 的密钥,他们使用这些密钥构建从教育科技应用程序到文字游戏到 Twitter 机器人的各种内容!我们的原始架构自 2010 年以来已处理了超过 20 亿次调用,并且在很大程度上一直是一项免费服务。当 Wordnik 在 2014 年底作为非营利组织重新推出时,我们意识到必须将我们的 API 货币化,以创建可持续发展的未来发展基础,并且为了实现货币化,我们需要降低运营成本并引入新功能——我们的先前架构都没有简化这两者。输入 AWS Lambda+API Gateway!通过将我们当前的 API 分解成微小的函数,我们可以利用当前的微服务热潮,而无需担心运营方面的麻烦。通过使用 Elastic Beanstalk 和 3Scale 管理反向代理,处理旧 API 调用和新 API 调用之间的路由以及管理计费也变得更加容易。在顶部添加一个漂亮的 Swagger 界面,您就可以开始了……更快、更便宜!


11月4日

测试与监控
使用 Cucumber 测试您的 API | 上午 11:15 – 下午 12:45
Ole Lensmar,SmartBear 软件首席技术官
使用 Cucumber 的 BDD 越来越受欢迎,因为它允许使用自定义领域特定语言表达需求,这些语言可以作为测试执行以验证实际的实现。API 特别是在这种方法中似乎有很多收获,因为它们通常在本质上是技术的;似乎正确执行的 Cucumber 实现应该允许越来越多的非技术利益相关者参与定义 API 行为和功能的需求。但是,Cucumber 词汇表可以变得多么“非技术化”来描述像 API 这样固有的技术事物?何时使用命令式方法与声明式方法更有意义?如何将简单的语言转换为复杂的有效负载和验证?随着 API 复杂性的增加,Cucumber 的使用如何扩展?以及像 Swagger 这样的标准如何使 Cucumber 测试更加直观?我知道您很想知道——所以不要错过这个采用 API 黄瓜涅槃之路的机会!

金融科技
OpenAPI 超越 API 文档 | 下午 2:00 – 下午 3:30
Arnaud Lauret,AXA Banque IT 架构师
OpenAPI 提供了许多可能性,涵盖整个 API 生命周期,但它仅被视为生成 API 文档的解决方案。本课程将讲述 AXA Banque 从 .doc 和 .pdf API 文档到广泛使用 OpenAPI 规范(以前称为 Swagger)的演变历程。在整个过程中,我们将确定 API 定义语言除了简单地生成 API 文档之外的许多优势,包括设计、测试、文档持续交付、代码生成、模拟和原型设计新想法。

站在巨人的肩膀上:Capital One 如何构建其 API | 下午 2:00 – 下午 3:30
Abdelmonaim Remani,Capital One DevExchange 工程技术主管


自REST架构风格首次引入以来,就一直存在着高度模糊性和大量歧义的问题。早期缺乏具体的参考实现,导致最流行的Web API成为了事实上的标准。为了赢得每一位Web开发者的青睐,领先的科技公司投入巨资构建RESTful API,并投入大量资源推广他们各自的REST版本。Capital One也不例外。尽管对于像它这样规模的金融机构来说,这可能看起来违反直觉,并且在一个受限于过时技术和法规约束的行业中扮演角色也极具挑战性,但Capital One正全面投入一项公司范围内的计划,通过使用最新、最优秀的开源技术实现的内部和面向公众的API来公开金融服务。本次演讲将探讨Capital One如何使用REST,在其中,风险和赌注都远高于为客户提供错误的转向路线。

API 全生命周期工具支持 | 下午2:00 – 3:30
史蒂文·丰塞卡,首席服务架构师,Intuit
本次演讲的重点是展示Intuit内部的一个名为API生命周期管理器的工具,这是一个Web应用程序和一组API,使IT组织能够在其生命周期的各个阶段(从构思到淘汰)高效地生成API。听众将了解Intuit IT如何协调战略性API组合的构建,包括其功能分配和服务所有权、包含当前行业建模语言中找不到的创新的全面合同文档、文档生成和交付。API生命周期管理器的示例将以IT如何帮助Intuit产品交付愉悦的客户体验的故事为背景进行展示,尤其是在基于订阅的计费和商业领域。

加入我们参加OpenAPI规范研讨会

作者: 博客

OpenAPI Initiative和Capital One联合主办2016年APISTRAT大会的一部分——OpenAPI规范速成课程。

在此注册.

第一部分:OpenAPI规范简介

本研讨会将介绍用于指定API的新OpenAPI格式。该格式是Linux基金会OpenAPI Initiative的核心规范,也是使用最广泛的API定义格式。研讨会将包括

  • OpenAPI格式及其起源于Swagger规范的概述。
  • 演讲者涵盖现场示例,详细介绍何时、何地以及如何使用OAI格式。
  • 对格式未来发展方向的高级概述。

 

第二部分:深入探讨OpenAPI规范

本研讨会的第二部分为用户和正在评估该格式的人员提供了对OpenAPI格式的深入了解。该格式是Linux基金会OpenAPI Initiative的核心规范,也是使用最广泛的API定义格式。本部分研讨会涵盖的主题包括

  • 对OpenAPI规范的技术深入探讨,包括实例。
  • 使用该格式的工具和服务的概述。
  • 关于即将推出的v3格式及其可能包含内容的讨论。
  • 有关如何参与OAI并为OpenAPI规范做出贡献的信息。

 

请求参数:解释3.0规范,第3部分

作者: 博客

随着OpenAPI规范3.0版本即将进入候选beta阶段,这一系列文章旨在从技术开发者社区(TDC)的角度提供对正在发生变化的内容以及如何变化的见解。第一篇文章描述了规范未来演变的背景和基本原理,第二篇文章涵盖了结构性更改,接下来的几篇文章将讨论协议、文档和其他剩余的开放项目。

请求参数

在OpenAPI 2.0中,所有可能变化的请求消息部分,包括URL参数、标头和正文,都被描述为一组类型化的参数。经验表明,将HTTP请求正文的描述映射到与查询和标头参数相同的元数据集中存在许多挑战。今天,让我们来分解这将如何影响请求正文、内容对象和Cookie参数。

请求正文

一个新的属性requestBody已添加到操作对象中。作为一个命名属性,这提供了与参数对象更好的区分,并简化了它,此外,它也更容易描述请求正文本身。

内容对象

OpenAPI 2.0在以下方面建立了一种复杂的关系:

  1. 声明响应媒体类型的位置
  2. 定义响应模式和示例的位置

可以在全局定义多个响应媒体类型,但可以在操作级别可选地覆盖它们。但是,这允许为每个响应对象定义一个模式,尽管可以通过媒体类型定义示例,或者每个模式定义一个示例。这使得难以针对不同的媒体类型定义不同的模式,以及针对不同的响应对象使用不同的媒体类型。

为了解决这个问题,内容对象在响应对象、媒体类型和模式之间引入了一种简单关系。每个响应对象包含一个内容类型对象,用于每个支持的媒体类型。每个内容类型对象都有一个模式和一个用于该媒体类型的示例数组。

内容对象也用于请求正文,并且在描述入站有效负载方面的工作方式相同。这神奇地消除了对producesconsumes数组的需求。关于是否也利用内容对象来描述复杂的URL参数和响应标头值的讨论仍在进行中。

这些更改导致路径项具有以下结构

contentobjects

Cookie参数

虽然TDC成员一致认为,虽然使用Cookie传递参数并非最佳实践,但仍有足够多的人表达了希望描述现有的基于Cookie的API,因此需要包含一个新的参数类型

在下一篇文章中,我们将介绍要支持的新交互模式以及一些计划对有效负载描述进行的更改。

  • 第1部分 – 背景以及如何参与!
  • 本系列的上一篇文章:第2部分 – 结构性更改

TDC:结构性改进:解释3.0规范,第2部分

作者 博客

随着OpenAPI规范3.0版本即将进入候选beta阶段,这一系列文章旨在提供对正在发生变化的内容以及如何变化的见解。第一篇文章描述了规范未来演变的背景和基本原理,接下来的几篇文章将介绍技术开发者社区(TDC)迄今为止取得的进展。

为了组织工作,创建了六个综合元问题

  1. 结构性改进
  2. 请求参数
  3. 协议和有效负载
  4. 文档
  5. 安全
  6. 路径定义

在接下来的几周内,我们将按顺序描述每个问题。今天,我们将介绍…

结构性改进

OpenAPI的下一个版本将进行一些相当重大的更改——在语义版本控制术语中,这将代表从2.0到3.0的重大更改。由于重大更改事件很少发生,因此它们提供了进行全面结构改进的机会。

最重要的是,在OpenAPI规范3.0版本中,文档的整体结构得到了简化

pasted-image-0

新版本标识符

从曾经称为Swagger 2.0现在称为OpenAPI规范的描述开始过渡的一个显而易见的地方?在2.0中称为swagger的version属性将替换为openapi版本标识符。将来,此版本标识符将遵循语义版本控制的约定,因此它将包含三个部分:主版本.次版本.修订版本,这很可能意味着3.0.0。这也解释了为什么该值是字符串而不是数字,并且它将允许将来对规范进行更受控制且可识别的更改。

组件对象

OpenAPI 2.0在顶级属性的行为方面有些不一致。例如,某些属性包含应用于API的全局元数据,而其他属性则用作可重用元数据片段的容器,以便在其他地方引用。为了阐明这一点并最大程度地减少顶级属性的数量,将引入一个新的components属性。此components属性仅包含将在文档其他地方引用的可重用元数据。

pasted-image-0-1

多个主机

OpenAPI 2.0允许指定单个主机和basePath,但schemes属性允许同时指定http和https,因此实际上启用了两个仅在方案上不同的主机。在OpenAPI.vNext(规范存储库的工作分支)中,新的顶级hosts对象包含一个对象数组,这些对象包含host、basePath和scheme属性。通过将其构建为对象数组,可以支持API的任意数量的根URL,并且它允许更清晰地关联scheme、host和basePath属性。它还减少了所需的顶级属性数量,简化了文档结构。

hosts

在围绕GitHub问题和相关拉取请求的讨论中,TDC解决了路径是否可以识别为表示不同环境(例如开发、测试和生产)的问题。但是,这暗示了不同的主机可能指向不同的API实现,而这并非支持API的多个根URL的意图。相反,目标是允许为同一API定义一组别名。(注意:关于主机和basePath的参数化仍然存在一个未解决的问题,这可能允许指向不同的环境。)

此外,主机、basePath 和 scheme 可以在路径项级别被覆盖。这应该可以更容易地将由单独主机提供的功能整合到 API 描述中。

pasted-image-0-2

更具描述性的选项

新的规范允许用户以更面向资源的方式描述他们的 API。以前,API 行为的描述是在操作级别定义的。对于以面向资源的方式设计的 API,文档文本通常会写成“获取 foo”、“发布 foo”、“删除 foo”。如果需要详细说明“foo”的目的,则需要在每个操作中重复这些文本。现在,一个路径项对象可以包含简短的摘要文本和较长的描述文本。是否在操作级别提供额外的描述由用户决定,这取决于是否需要进一步的解释。

示例对象

描述示例的选项已大幅扩展。之前的规范表明,示例只能通过 JSON 或 YAML 对象来描述。现在,通过使用 JSON 字符串,可以描述任何格式的示例。此外,可以使用 $ref 对象指向包含示例的外部文件。示例的结构化方法仍在不断变化,可能取决于 TDC 是否接受提议的内容对象。内容对象包含一个示例对象的数组,用于为每种媒体类型定义一个或多个示例。

如您所见,关于结构变化的这个元问题有很多内容需要消化。下一篇文章将讨论 OpenAPI 3.0 中如何描述请求的更改。

  • 本系列上一篇文章 第 1 部分 – 背景 以及如何参与!

 


Darrell Miller关于作者

Darrel Miller
Darrel Miller 是 Microsoft Azure API Management 的高级软件开发工程师。Darrel 是 OpenAPI 规范技术开发人员社区的成员。您可以在 Twitter 或他的博客 Bizcoder 上关注他。