OpenAPI Initiative

观看 IBM developerWorks Open 的录音，OAI 董事会成员 Jeff Borek (@jeffborek) 主持了与 OAI 成员 Capital One 的 Dennis Brennan (@dennis_brennan)、Apigee 的 Marsh Gardiner (@earth2marsh) 和 SmartBear Software 的 Tony Tam (@fehguy) 以及 StrongLoop 的 Raymond Feng (@cyberfeng) 的讨论。

 

链接

• 图表 - Open API Initiative 6 个月
• 文字记录 - Open API Initiative 6 个月
• 问答 - Open API Initiative 6 个月

去年，我很失望错过了 Gluecon。我的同事们对它评价很高 - 信息丰富、先进，而且非常不商业化。我很高兴今年它与我的日程安排相符，而且我一点也没失望。Eric Norlin (@defrag) 做了很棒的工作，确保他的演讲者种类繁多，但有一点共同点：质量极高。

我之所以很兴奋，也是因为这是我自 Open API Initiative 成立和 Open API Specification 更名以来参加的第一个活动，我想它会受到一些关注。然而，我不知道它会引起多少关注。

在 API 轨道上，几乎没有一个环节不提及 Open API（好吧，在某些情况下...多次提及），或者说（好几次演讲者口误，称之为“Swagger 规范”。

最令人兴奋的不是更名，当然。每个演讲者如此频繁地提及它的原因是，它提供了一种通用语言，一个我们可以共同参考的讨论 API 的接触点。组建该倡议的目标是让行业能够超越关于哪种格式更好以及为什么更好的讨论 - 这样我们就可以专注于工具链和生态系统，这些工具链和生态系统可以在我们都同意一种通用语言的情况下实现。

API 轨道很棒。LaunchAny 的 James Higginbotham 在 领域驱动设计 和 API 定义中抽象的重要性方面发表了讲话。Apiary.io 的 Emmanuel Paraskakis、SmartBear（以及 Swagger 项目）的 Tony Tam 以及 StrongLoop 的 Ray Camden 都谈到了提高 API 开发工作流程的速度和规模。来自 Restlet 的 Guillaume LaForge 以他的演讲结束了 API 轨道，演讲主题是“五面棱镜极化 Web API 开发。”（！）

如果第一天五场 API 环节还不够，第二天还有不少于八场与 API 相关的环节。对我来说，最棒的时刻之一是 Mark Stafford 关于他的 Model First 项目的演讲 - 一个用于 Open API 规范组合的框架，它有助于强制一致性并简化开发（运行 这里，代码 这里）。

但是，会议中最精彩的 API 片段必须是 IBM 的 Stewart Nickolas 关于“对话式计算”的演讲。他的整个演讲几乎都是通过与 Watson 的语音交互完成的...包括 询问 Watson 有关 API 的问题、让 Watson 描述 Open API 规范，然后让 Stewart 口头告诉 Watson 调用 API。

不知何故，我怀疑开发者将来不会以口头方式对 API 进行太多反思。但它仍然是一个非常强大的演示，尤其是在我考虑到整个演示都是由...API 提供支持的情况下。

—
关于作者
Dan Ciruli
Dan Ciruli 是 Google 的产品经理，负责 API 基础设施。他以前在有膝盖的时候玩了很多极限运动，在有时间的时候写了很多软件。如果你给他机会，他会尝试用西班牙语和你说话。你可以在 Twitter 上找到他，他的用户名是 @danciruli。

Gluecon 即将到来，Open API Initiative 正在赠送一张免费通行证。要符合资格

1. 找到任何将 **Swagger Specification*** 而不是 **OpenAPI** 作为参考的开源项目，无论是在文档中还是在代码库本身中。
2. 将这些引用更新为反映新名称 **OpenAPI**（参见此示例 此处）
3. 如果您已经是合作者，请推送更改。如果您已将项目分叉，请提交包含更改的拉取请求。
4. 在 Twitter 上发布您工作（提交或 PR）的链接到 @OpenApiSpec，并附上您的 GitHub ID

OAI Gluecon 团队将选出一位幸运者！参加 Gluecon 从未如此简单。

*注意：这仅适用于引用 Swagger 规范的规范。有关名称更改的历史记录，请单击 此处。

详情：赠送活动仅限于 Gluecon 入场券，参加者需自行负责旅费和住宿。

 

—
关于作者
Marsh Gardiner
关于 Marsh，以下三条陈述中至少有两条是正确的：没有人比他更爱 API。他是一个困在产品人员身体里的开发者。他讨厌写简介。

在 Marsh 事业的半随机行走中，他为 EA 和 Fox 制作了电子游戏，创建了交互式学习环境，推出了一个教育非营利组织，并在 2009-2018 年的 API 战争中英勇奋战。在 Apigee，他设想了一个更美好的应用程序和 API 未来。

我们今天的客座文章来自 CoreOS 的 Brandon Phillips。 CoreOS 为 Linux 容器构建开源项目和产品。他们用于共识和发现的旗舰产品 (etcd) 以及他们的容器引擎 rkt 是 gRPC 的早期采用者，gRPC 是一个基于 protobufs 和 HTTP/2 的 RPC 框架，可以使构建和使用 API 更轻松，性能更高。由于许多客户端使用 http/1.1 加上 json，因此与 JSON 和 Open API 的互操作性非常重要。对于更习惯于 HTTP/1.1+JSON 驱动的 API 和 Open API Initiative 规范（以前称为 swagger）API 的用户，他们正在使用组合开源库来以这种形式提供他们的 gRPC 服务。他们已经构建了 API 多路复用器，为用户提供两全其美的方法。让我们深入了解细节，看看他们是如何做到的！

这篇文章最初发表在 CoreOS 博客 (链接)。我们在此转载，并进行了部分编辑。

 

CoreOS 选择 gRPC 的关键原因之一是它使用 HTTP/2，使应用程序能够在一个 TCP 端口上同时提供 HTTP 1.1 REST+JSON API 和高效的 gRPC 接口。（适用于 Go）这使开发人员能够与 REST 网络生态系统兼容，同时推进一种新的、高效率的 RPC 协议。随着 Go 1.6 最近发布，Go 默认情况下附带了一个稳定的 net/http2 包。

一个名为 EchoService 的 gRPC 应用程序

在这篇文章中，我们将从 gRPC API 定义构建一个小型的概念验证 gRPC 应用程序，添加 REST 服务网关，最后将它们全部提供在一个 TLS 端口上。该应用程序称为 EchoService，是 shell 命令 echo 的网络等效项：该服务将返回或“回显”发送给它的任何文本。

首先，让我们在一个名为 EchoMessage 的 protobuf 消息中定义 EchoService 的参数，其中包含一个名为 value 的字段。我们将在一个名为 service.proto 的 protobuf“.proto”文件中定义此消息。这是我们的 EchoMessage

message EchoMessage { string value = 1; }

在同一个 protobuf 文件中，我们定义了一个 gRPC 服务，它接收此数据结构并返回它

service EchoService { rpc Echo(EchoMessage) returns (EchoMessage) { } }

将此 service.proto 文件通过 Protocol Buffer 编译器 protoc 运行，将在 Go 中生成一个存根 gRPC 服务，以及各种语言的客户端。但是 gRPC 本身不像一个也暴露 REST 接口的服务那样有用，因此我们不会止步于 gRPC 服务存根。

接下来，我们添加 gRPC REST 网关。此库将在 gRPC EchoService 之上构建一个 RESTful 代理。要构建此网关，我们在 EchoService proto 中添加元数据，指示 Echo RPC 映射到一个 RESTful POST 方法，并将所有 RPC 参数映射到一个 JSON 主体。网关可以将 RPC 参数映射到 URL 路径和查询参数，但为了简洁起见，这里省略了这些复杂情况。

service EchoService { rpc Echo(EchoMessage) returns (EchoMessage) { option (google.api.http) = { post: “/v1/echo” body: “*” }; } }

实际上，这意味着网关在由 protoc 生成后，现在可以接受来自 curl 的类似以下请求。

curl -X POST -k https://localhost:10000/v1/echo -d ‘{“value”: “CoreOS is hiring!”}’

到目前为止，整个系统看起来像这样，只有一个 service.proto 文件生成 gRPC 服务器和 REST 代理。

带有 REST 网关的 gRPC API

为了将所有这些整合在一起，echo 服务创建了一个 Go http.Handler 来检测协议是否为 HTTP/2 以及 Content-Type 是否为“application/grpc”，并将此类请求发送到 gRPC 服务器。其他所有内容都路由到 REST 网关。代码看起来像这样。

if r.ProtoMajor == 2 && strings.Contains(r.Header.Get(“Content-Type”), “application/grpc”) { grpcServer.ServeHTTP(w, r) } else { otherHandler.ServeHTTP(w, r) }

要试用它，您只需要一个 可用的 Go 1.6 开发环境 以及以下简单的咒语。

$ go get -u github.com/philips/grpc-gateway-example $ grpc-gateway-example serve

服务器运行后，您可以在 HTTP 1.1 和 gRPC 接口上尝试请求。

grpc-gateway-example echo 使用 gRPC 从 REST 中休息一下 curl -X POST -k https://localhost:10000/v1/echo -d ‘{“value”: “CoreOS is hiring!”}’

最后一个好处：因为我们有 Open API 规范，所以您可以浏览 Open API UI，它运行在 https://localhost:10000/swagger-ui/#!/EchoService/Echo（如果您在笔记本电脑上运行了上面的服务器）。

gRPC/REST Open API 文档

我们已经了解了如何使用 gRPC 连接到 REST 世界。如果您想查看完整项目，请查看 GitHub 上的仓库。我们认为使用单个 protobuf 来描述 API 的这种模式可以带来易于使用、灵活的 API 框架，我们很高兴在更多项目中利用它。

—

关于作者
Brandon Phillips (CoreOS)
Brandon Philips 作为 CTO，正在帮助 CoreOS 构建现代的 Linux 服务器基础设施。在加入 CoreOS 之前，他在 Rackspace 从事云监控工作，并在 SUSE 担任 Linux 内核开发人员。作为俄勒冈州立大学开源实验室的毕业生，他对开源技术充满热情。

Linux 基金会要求我在今年早些时候在太浩湖举行的 Linux 协作峰会上进行 闪电演讲。我很高兴代表 Open API Initiative 发言，并谈论对开放 API 的日益增长的兴趣以及 Swagger 项目的未来。规范现在由这个 Linux 基金会工作组指导，这对我们来说意义重大，我们 IBM 对规范的未来发展以及相关代码库感到兴奋，因为我们将与项目创始人 Tony Tam 和更大的社区合作，推广开放 API 技术。

点击下面的图片观看我在 2016 年 3 月 27 日的 3 分钟演讲。您也可以在 Twitter 上关注我：@jeffborek

—

关于作者
Jeff Borek
Jeff Borek（IBM 开放技术与合作伙伴关系全球项目总监）是一位资深技术和传播主管，在软件、电信和信息技术/咨询行业拥有超过 20 年的领导和技术经验。他目前是开放技术与合作伙伴关系团队的业务开发负责人，与客户、业务合作伙伴、领先的行业分析师以及各种开源社区计划合作，包括：Linux 基金会、OpenStack 云软件项目和 Cloud Foundry 基金会。他还代表 IBM 担任 Docker 治理咨询委员会的现任主席，但对我们来说最重要的是，他担任 Open API Initiative 的董事会成员。您可以在 Twitter 上关注他。

以下是关于 OAI 内部情况的快速更新。

新成员

人们一直对加入 OAI 感兴趣，我们很高兴欢迎两个新成员加入该组织。

• Apiary：API 设计和协作工具的创建者，最近宣布支持 Swagger / OpenAPI Spec。
• Atlassian：JIRA、Confluence、HipChat、Bamboo 等背后的团队。

如果您的组织有兴趣加入 OAI 以支持 OpenAPI 规范的演进和普及，请查看 https://www.openapis.org.cn/join，了解如何加入的详细信息。

初步 TDC 成员资格和流程确定

推动 OpenAPI 规范的技术开发者社区的初始成员已确定；

• Darrel Miller - @darrel_miller
• Jason Harmon - @jharmn
• Jeremy Whitlock - @whitlockjc
• Marsh Gardiner - @earth2marsh
• Ron Ratovsky - @webron
• Tony Tam - @fehguy

此贡献者列表在 GitHub 上维护，符合 OAI 章程。

规范演进的流程已由 TDC 在 https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md 上发布。

OpenAPI Spec 3.0 工作进展

规范的下一个主要迭代工作已经开始，关于各种功能/改进的讨论正在 GitHub 上的相应问题中进行。如果您有兴趣了解或参与，以下是一些指向正确方向的链接。

• GitHub 上的 OpenAPI.next 分支
• 下一个版本的提议问题列表

OAI 代表参加活动

OAI 将由其成员代表参加欧洲的两个即将举行的 OW2 活动。

• 云计算世界博览会，巴黎，3 月 23-24 日 - 由 Restlet 代表。
• 云计算博览会欧洲站，伦敦，4 月 12-13 日 - 由 3Scale 代表。

OAI 目前正在评估其参与全球即将举行的 API 相关活动的可能性；如果您正在组织一个希望 OAI 代表参加的活动，或者您有兴趣组织一个 OAI 可以赞助的当地 OAI/OpenAPISpec 聚会，请不要犹豫 与我们联系。

其他正在进行的活动

• 我们已分配了一个内部工作组来提供关于 OAI 徽标和标记使用指南 - 这些指南将在我们的网站上发布。
• OpenAPI 规范现在有一个 Twitter 帐户，地址是 https://twitter.com/openapispec - 关注它以获取有关 OAI 和 OpenAPI-Spec 相关新闻的通知。

现在就这些 - 如果您有兴趣参与有关 OpenAPI 规范的技术讨论，请不要犹豫 在 GitHub 上联系 TDC - 或者如果您有任何一般性问题，请通过我们的 联系表格 联系 OAI 成员 - 我们期待您的来信。

/Ole Lensmar
@olensmar

在年底的各种活动中，OAI 一直忙于为 2016 年做好所有最初的准备工作。我们在去年 12 月的会议中取得了以下成果。

1. OADF 更名为“OpenAPI 规范”

最初为该规范提出的名称是 OADF（“Open API Definition Format”） - 这是一个似乎需要用更吸引人的名称来代替的名称；OAI 的成员决定将“OpenAPI Specification”（简称“OAS”）作为新的名称，从现在开始使用。

2. Swagger 规范存储库迁移到 GitHub 上的 OAI

Swagger 2.0 规范存储库因此已从其在 GitHub 上 swagger-api 组织下的原始位置迁移到新的 OAI 组织，名为“OpenAPI Specification” - https://github.com/OAI/OpenAPI-Specification.

目前规范本身还没有更改，以免破坏任何与 Swagger 2.0 定义一起使用的现有工具。OAS 的下一个版本将弃用规范中任何对“swagger”一词的使用，而使用 OAS 特定的术语；TDC 将负责实施此转换。

OAS 将继续根据 Apache 2.0 许可证获得许可。

3. 新的 OAI 成员

在 OAI 首次启动后，加入 OAI 的兴趣非常强烈 - 我们很高兴欢迎以下公司加入该组织；

• APInf - 来自 https://apinf.io/
• Mashape - https://www.mashape.com/

如果您或您的组织有兴趣加入 OAI，请随时与 OAI 联系，网址为 https://www.openapis.org.cn/join。

4. 新的 OAI 领导层正在形成

OAI 章程指定了 3 个实体，构成了其治理结构。

1. 成员委员会，负责制定整个小组的章程，并管理非技术任务。
2. 技术开发委员会 (TDC)，负责 OAS 演变的实际技术工作。
3. 技术监督委员会 (TOB)，负责解决 TDC 中的任何冲突，并确保 TDC 按照 OAI 的核心价值观交付。

TDC 和 TOB 的组建仍在进行中；目前，以下人员已被选举。

• TDC 成员：<正在进行中>
• TOB 成员
  • 由 OAI 成员选举：Tony Tam，Ron Ratovsky，Jason Harmon
  • 由 TDC 成员选举：<正在进行中>
• OAI 主席：Ole Lensmar

下一步

随着 OAI 的逐渐成形，我们有以下议程安排。

• 完成 TDC 和 TOB 的成员资格
• 在 TDC 内部开始下一版 OAS 的工作
• 决定 OAI 可以参与哪些非技术活动，以促进 OAS 的进一步演变及其在行业中的采用。

我显然对我们未来的发展感到非常兴奋 - 行业对 API 的推动势头没有显示出任何减缓的迹象，而对 API 定义通用语言的需求是显而易见的，因为企业努力最大限度地利用 API 为其最终用户提供价值。

新年快乐！

/Ole Lensmar