像 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