使用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/articles/openapi/?useSponsorshipSuggestions