使用OpenAPI构建更智能的API
2019,8,19 博客

OpenAPI可以驱动强大的测试自动化，它可以用于生成模拟数据，从而让开发人员中更能分析出其复杂性。你可以利用OpenAPI的隐藏优势（如链接和回调）来使开发人员脱离文档而直接通过代码了解。本文主要介绍如何使用OPENAPI构建更智能的API。

毫无疑问，如今已经是API主宰的时代。即使是传统而非技术公司（这样单一产业的公司越来越少）也将API视为关键产品。越来越多的公司使用API作为沟通手段，这是不同团队之间分享工作和沟通的基本单位。许多人试图效仿亚马逊的成功，亚马逊的内部和外部API数量和质量都在不断上升。

这是比较准确的OpenAPI单行描述：“ 机器可读取到的接口文件的规范”。在这个描述的背后隐藏着一些非常实用的技术，它允许你以机器可以使用的方式描述API，而且机器可以做的事情对于构建API的团队以及软件开发人员来说非常有用。

REST API

严格来说，专业术语“API”涵盖了很多方面，本文专注的是基于HTTP的API，简称为REST。Web API的数量正在以前所未有的速度激增，私人服务器中的API越来越像用于云服务的API，开放在互联网上。

许多开发人员不再需要生成代码中实际存在的API接口，而是生成提供由文档、注册信息、代码生成等组成的编程描述。OpenAPI不是描述API的唯一规范，但的确是一个优势越来越突出的标准。

在OpenAPI中描述API是所有过程的第一步。人工阅读的文档是一个明显的输出，OpenAPI还可以教育机器使用已有的API来进一步简化人工的工作并自主运作。随着向OpenAPI提供越来越多的信息，可以开始将人的工作转移到机器和工具上。某种意义上OpenAPI是一种产品，可以减少开发人员的重复工作量。

OPENAPI 示例

可以用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规范允许开发人员使用代码探索技术了解API。

OPENAPI3.0

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

通常，API调用的结果可以用作另一个API调用的输入，最简单的例子是在其返回结果中看到了包含文字链接的API。OpenAPI的链接功能添加了描述不同API之间链接的静态元数据，以及如何使用一个API的输出作为另一个API的输入。很高兴看到更多的OpenAPI文档使用链接和更好的工具来指定链接。

注册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项目开始的地方，有一些常用的Web框架工具可以从代码中提取规范（在某些情况下由附加的注释或备注辅助）。

无论是契约优先还是代码优先，它实际上取决于开发时的流程。对于大型组织而言，契约优先可能是在同一页面上明确地获取服务器和客户团队的正确方法。在编写服务器代码时，客户端团队可以针对自动生成的模拟进行编写。对于客户端和服务器一起开发的或API本身就是产品的项目，代码可能就足够了。

接下来应该做的最重要的事情就是发布它，并使其保持最新。通过发布API文档，可以了解开发人员使用API的工具。模拟测试意味着开发人员可以花更少的时间来了解API的细节并且花充足的时间构建。随着OpenAPI及其工具生态系统的发展，随着框架和平台变得更加智能，API的作用正变得越来越全面。

 

参考资料：Adam Leventhal，Using OpenAPI to Build Smart APIs for Dumb Machines

原文地址：https://www.infoq.com/articles/openapi/?useSponsorshipSuggestions