OpenAPI规范简介

banq 18-08-19
         

API开发从来都不是一项容易的任务,而不断发展的API则更加复杂。

我们如何确保不经意间地发布实际会对API实行了重大更改? 我们如何交流怎样使用API? 我们如何记录我们的API? 我们如何自动化API的测试? 我们能不能做到这一切,并保持技术不可知论?

有大量的工具可供我们使用,然而,没有一个是“恰到好处”的。

我们有一个选择: 消费者驱动合同,ThoughtWorks总结如下:

在消费者驱动合同中,每个消费者在一个单独的合同中记录他们对提供者的期望。所有这些合同都是和服务提供者共享,提供者可以创建一个测试套件来验证这些他们应该履行的义务。这可以让他们保持敏捷,做出不影响任何消费者的改变。

简而言之,“合同”可以看作是一种请求/响应。你给API一个X,并且可以期望api返回一个Y,合同契约是一种定义API交互的技术。

然而,合同在记录API方面做得很差。

对于发布公共API的情况,我们需要一种与技术无关的方法来记录我们的API。目前,开放API在这个领域是一个明确的领导者。

2015年,SmartBear捐赠了用于OpenAPIInitiative的swagger2.0规范。这开启了OpenAPIInitiative的形成,这是一个由多家公司组成的联盟,包括:3 Scale、Apiges、Capital One、Google、IBM、Intuit、Microsoft、PayPal和Restlet。

在2017年夏天,OpenAPI倡议发布了开放API 3.0规范。(跟“Swagger”这个名字说再见)

OpenAPI3.0规范可以用JSON或YAML编写,并且在记录RESTfulAPI方面做得很好。

开放API规范定义API交互。

OpenAPI3.0规范是也定义扩展。

通过使用OpenAPI规范扩展,我们可以定义消费者驱动的契约。