像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的输入和输出。
...