使用OpenAPI构建更智能的API

像OpenAPI这样的API描述规范是一个关键工具，您应该尽量地将其好好掌握，记录和执行API的工做由计算机和开发人员完成；OpenAPI 3.0如今容许额外的表现力，可让机器为咱们作更多有用的工做；OpenAPI能够驱动强大的测试自动化，它能够用于生成模拟，它甚至能够模拟进行本机绑定，从而让开发人员中更能分析出其复杂性；您能够利用OpenAPI的隐藏优点（如连接和回调）来使开发人员脱离文档而直接经过代码了解。本文主要介绍如何使用OPENAPI构建更智能的API。

不容置疑，现在已是API主宰的时代。即便是传统而非技术公司（这样单一产业的公司愈来愈少）也将API视为关键产品。愈来愈多的公司使用API​​做为沟通手段，这是不一样团队之间分享工做和沟通的基本单位。许多人试图效仿亚马逊的成功，亚马逊的内部和外部API数量和质量都在不断上升。在2020年即将重拍的电影《毕业生》中，导演对想要进行数字重建的年轻人达斯汀霍夫曼的一个建议是认可他的将来将是“API”。

这是我能够挖掘的最引人注目的OpenAPI单行描述：“ 机器可读取到的接口文件的规范”。在这个标语口号的背后隐藏着一些很是实用的技术。是的，它容许您以机器可使用的方式描述您的API，可是机器能够作的事情对于构建API的团队以及使用它们的软件开发人员来讲很是有用。

热切的学习者

当我仍是个孩子时，API引用法则被写在书中，我开始细读和熟悉它们。好比开发人员指南、Palm编程、Java 3D API规范等，那时蒂姆奥莱利（著名出版社）但是拿走我很多的书钱。这些书籍是你学习API如何运行的途径，不只仅是关于你想要操做的系统或平台，还有关于如何实现它的细节，和一系列API参考例子。这种学习资料分布在在网络上，咱们意识到须要一个平台来教授全部人即使是热心的学习者，教育咱们一个道理——构建它们的人和使用咱们构建的API的人同样重要。

严格来讲，专业术语“API”涵盖了不少方面，因此在这里为了作统一，本文我将专一于的是基于HTTP的API。我称之为REST。Web API的数量正在之前所未有的速度激增，咱们私人服务器中的API愈来愈像用于云服务的API，开放在互联网上。我也不是在谈论像WSDL这样的古董，或者像GraphQL那样的新热点（虽然我稍后会谈到它），只是几乎每一个SaaS供应商都发布的API都是简单易明的。

许多开发人员再也不须要生成代码中实际存在的API接口，而是须要生成能够提供由文档、注册信息、代码生成等组成的编程描述。OpenAPI不是描述API的惟一规范，但确是一个优点彷佛愈来愈突出的标准。像AWS，Google和Palantir使用的是他们本身的API规范，通常由于他们的规范指定得较早，或者有不一样的要求，或者甚至发现像OpenAPI这样的规范的说法不够充分。而我会倾向于OpenAPI，由于它的人气飙升已经催生了大量的工具（包括咱们本身的API-SQL层）。

在OpenAPI中描述API是全部过程的第一步。咱们人工阅读的文档是一个明显的输出，但OpenAPI还让咱们教育机器使用咱们的API来进一步简化人工的事情并自主运做。随着咱们向OpenAPI提供愈来愈多的信息，咱们能够开始将人的工做转移到他们使用的机器和工具上。某种意义上API是一种产品，能够减小开发人员的重复工做量。

OPENAPI 101

能够用JSON或YML指定OpenAPI文件，下面是Strava OpenAPI文档的一个片断：

"paths": {

"/athletes/{id}/stats": {

"get": {

"operationId": "getStats",

"summary": "Get Athlete Stats",

"description": "Returns the activity stats of an athlete.",

"parameters": [

{

"name": "id",

"in": "path",

"description": "The identifier of the athlete. Must match the authenticated athlete.",

"required": true,

"type": "integer"

},

{

"$ref": "#/parameters/page"

},

{

"$ref": "#/parameters/perPage"

}

],

"tags": [

"Athletes"

],

您可使用工具（或手动）编写文档，也能够从代码（使用几乎任何语言）中生成文档。下面是Java中的一个示例，其中包括OpenAPI注释以及JAX-RS注释。

@GET

@Path("/{username}")

@Operation(summary = "Get user by user name",

responses = {

@ApiResponse(description = "The user",

content = @Content(mediaType = "application/json",

schema = @Schema(implementation = User.class))),

@ApiResponse(responseCode = "400", description = "User not found")})

public Response getUserByName(

@Parameter(description = "The name that needs to be fetched. Use user1 for testing. ", required = true) @PathParam("username") String username)

throws ApiException {

User user = userData.findUserByName(username);

if (null != user) {

return Response.ok().entity(user).build();

} else {

throw new NotFoundException(404, "User not found");

}

}

OpenAPI的最好输出是文档。一个好处是（具备至关智能的工做流程）内容能够保持最新，过期的文档是使人尴尬和无助的。同时OpenAPI让你的文档变得更加漂亮。您能够添加有用的组件（如交互式资源管理器）或自动生成更改日志，而不只仅是描述API的输入和输出。

无需人工的干预，OpenAPI能够驱动基于您所描述的内容发布API的模拟服务器。这些模拟API能够根据规范中的模式以及规范中代码的特定示例进行响应。这样，您的内部团队就能够在API彻底构建以前开始启动，并容许外部开发人员测试API的使用，而不会向服务器发送垃圾邮件（或者在得到通过身份验证的访问以前）。

咱们最先使用OpenAPI的一个方法是生成本地代码绑定。在咱们的例子中，咱们为前端生成了TypeScript绑定，以便与后端进行交互。这将API学习过程从代码和文档移到了IDE中。咱们能够依靠编辑器向咱们展现各类API的内容，包括正确的类型，而不是查看服务器代码来弄清楚它是如何工做的。发布API的OpenAPI规范容许开发人员使用代码探索技术（若是你喜欢Vim）了解它。

OPENAPI3.0

OpenAPI计划在一年多前发布了3.0版本。它包括一些很是酷但仍未充分利用的功能。最重要的是，它扩展了描述API的能力。很高兴看到OpenAPI在后续版本中增强了这一能力。3.0版还引入了两个很酷的新元数据：LINKS和CALLBACKS。

LINKS（连接）

一般，API调用的结果能够用做另外一个API调用的输入。您甚至可能已经在其响应主体中看到了包含文字连接的API。OpenAPI的连接功能添加了描述不一样API之间连接的静态元数据，以及如何使用一个API的输出做为另外一个API的输入。很高兴看到更多的OpenAPI文档使用连接和更好的工具来指定连接。

CALLBACKS（回调）

注册webhook时，一般会将URL做为字符串传入，而后该服务将调用该API。OpenAPI 3.0容许您描述回调的签名以及它应该具备的参数。再者，这很是有助于让开发人员脱离文档并经过代码发现问题。

更多

采用OpenAPI减轻了API建立者的负担，并试图有效地教育他们的用户，可是，当它让开发人员不只学得更好而学习更快时，它就是最有效的。OpenAPI能够作更多的工做来专一于教育开发人员使用的机器而不是开发人员本身。例如，考虑分页。如下是Google Calendar API教会用户对日历事件进行分页的方法：

输入：

pageToken：Token specifying which result page to return

输出：

nextPageToken：Token used to access the next page of this result. Omitted if no further results are available, in which case nextSyncToken is provided

仔细阅读的话，能够看出咱们应该从nextPageToken获取输出并将其插入到每一个连续调用的pageToken输入中，可是在OpenAPI（或Google的专有发现文档格式）中没法表达该语义。

总结

若是您已构建API或正在构建新API，请开始使用API​​描述规范。OpenAPI是愈来愈受欢迎的选择，但若是这对你不起做用的话，仍然会沿用选择其余的规范。当您能够越多地停留在人迹罕至的道路上，您就会愈加现工具或者生态系统带来的好处。

因而可知要构建更智能的API，有一个好的API编写规范是十分重要的。因为如今国内API市场产品众多，可是功能良莠不齐，找到一个全面并且稳定的很难。最近发掘了一个新的工具：EOLINKER，他们是作API研发管理服务，有详细的文档编写规则，页面也很清晰，最重要是支持读取代码注释生成文档，并且还支持零代码进行API测试。对API管理、监控等方面有兴趣的小伙伴自行了解下哦！https://www.eolinker.com

如何开始使用OpenAPI（或相似的文档规范）描述API的过程会遇到有争议的选择。对于契约优先的理论，API规范应该是API项目开始的地方，有一些经常使用的Web框架工具能够从代码中提取规范（在某些状况下由附加的注释或备注辅助）。

不管是契约优先仍是代码优先，它实际上取决于您本身开发时的流程。对于大型组织而言，契约优先多是在同一页面上明确地获取服务器和客户团队的正确方法。在编写服务器代码时，客户端团队能够针对自动生成的模拟进行编写。对于客户端和服务器一块儿开发的或API自己就是产品的项目，代码可能就足够了。只有符合要求在这些状况下，您能够从常见的Web框架派生OpenAPI文档（在某些状况下，能够借助其余注释）。

如今您已经得到了API描述，您应该作的最重要的事情就是发布它。发布它，并使其保持最新。充分利用内部使用：生成服务器缓存和本地代码，构建自动模拟，以及生成详细的文档。可是经过发布API文档，您能够了解开发人员用来使用API​​的工具。他们今天能够生成的示例，模拟测试意味着开发人员能够花更少的时间来了解API的细节而且花充足的时间构建。随着OpenAPI及其工具生态系统的发展，随着他们使用的框架和平台变得更加智能，API的做用正变得愈来愈全面。

原标题：Using OpenAPI to Build Smart APIs for Dumb Machines
做者：Adam Leventhal，Transposit的创始人兼首席执行官
原文连接：https://www.infoq.com/article...