像OpenAPI这样的API描述规范是您应该尽可能掌握的关键工具，记录和执行API的工作由计算机和开发人员完成；OpenAPI3.0现在允许额外的表现力，允许机器为我们做更多有用的工作；OpenAPI可以驱动强大的测试自动化，它可以用来生成mock，甚至可以模拟原生绑定，让开发者分析更复杂的；您可以利用OpenAPI的隐藏优势（如链接和回调）让开发人员脱离文档并直接进入代码。本文主要介绍如何使用OPENAPI构建更智能的API。毫无疑问，今天是API称霸的时代。即使是传统公司而非技术公司（在单一行业中越来越少见）也将API视为关键产品。越来越多的公司正在使用API作为通信手段，这是不同团队之间共享工作和通信的基本单位。许多人试图效仿亚马逊的成功，亚马逊在其内部和外部API的数量和质量上都有所增长。在即将于2020年翻拍的电影《毕业生》中，导演给一位想做数字重建的年轻人的建议之一，就是承认自己的未来是“API”。这是我能找到的最引人注目的OpenAPI单行描述：“机器可读接口文件规范”。这句标语背后隐藏着一些非常实用的技术。是的，它允许您以机器可以使用的方式描述您的API，但是机器可以做什么对于构建API的团队以及使用它们的软件开发人员来说非常有用。好学小时候，API引用的规律都是写在书本上的，我就开始细读、熟悉。比如开发者指南，Palm编程，Java3DAPI规范等等。当时TimO'Reilly（著名出版社）拿走了我很多书钱。这些书籍是您了解API工作原理的途径，不仅涉及您要操作的系统或平台，还包括有关如何实现它的详细信息，以及一系列API参考示例。这种学习材料分布在网络上，我们意识到我们需要一个平台来教导每个人，甚至是狂热的学习者，构建它们的人与使用我们构建的API的人一样重要。严格来说，“API”这个技术术语涵盖了很多方面，所以为了统一起见，我在本文中将重点介绍基于HTTP的API。我称之为休息。WebAPI的数量正在以前所未有的速度激增，我们私有服务器中的API越来越像云服务的API，在Internet上开放。我也不是在谈论像WSDL这样的老东西，或者像GraphQL这样的新热点（尽管我稍后会谈到），只是几乎每个SaaS供应商都发布了简单易懂的API。很多开发者不再需要生成实际存在于代码中的API接口，而是需要生成可以提供文档、注册信息、代码生成等的编程描述。OpenAPI并不是描述API的唯一规范，但它是一个强度似乎正在增长的标准。像AWS、谷歌和Palantir这样的东西都在使用他们自己的API规范，通常是因为他们的规范被指定得更早，或者有不同的要求，甚至发现像OpenAPI这样的规范说的不够充分。而且我倾向于OpenAPI，因为它的流行度激增催生了大量工具（包括我们自己的API-SQL层）。在OpenAPI中描述API是任何流程的第一步。我们人类阅读的文档是一个明显的输出，但OpenAPI还允许我们教机器使用我们的API来进一步简化人类的事情并自主操作。随着我们向OpenAPI提供越来越多的信息，我们可以开始将人们的工作转移到他们使用的机器和工具上。从某种意义上说，API是一种减少开发者重复工作量的产品。OPENAPI101可以在JSON或YML中指定OpenAPI文件，这里是StravaOpenAPI文档的一个片段："paths":{"/athletes/{id}/stats":{"get":{"operationId":"getStats","summary":"GetAthleteStats","description":"返回运动员的活动统计数据。","parameters":[{"name":"id","in":"path","description":"运动员的标识符。必须与经过身份验证的运动员相匹配。","re??quired":true,"type":"integer"},{"$ref":"#/parameters/page"},{"$ref":"#/parameters/perPage"}],"tags":["Athletes"]，您可以使用工具（或手动）编写文档或从代码（几乎任何语言）生成文档。下面是一个Java示例，其中包括OpenAPI注释和JAX-RS注释。@GET@Path("/{username}")@Operation(summary="通过用户名获取用户",responses={@ApiResponse(description="用户",content=@Content(mediaType="application/json",schema=@Schema(implementation=User.class))),@ApiResponse(responseCode="400",description="Usernotfound")})publicResponsegetUserByName(@Parameter(description="需要的名称获取。使用user1进行测试。",required=true)@PathParam("username")Stringusername)throwsApiException{Useruser=userData.findUserByName(username);if(null!=user){returnResponse.ok().entity(user).build();}else{thrownewNotFoundException(404,"Usernotfound");}}OpenAPI最好的输出是文档。一个好处是（通过相当智能的工作流程）内容可以保持最新，过时的文档令人尴尬且无益。同时，OpenAPI让您的文档更加美观。您可以添加有用的组件，如交互式浏览器或自动生成变更日志，而不仅仅是描述API的输入和输出。在没有人为干预的情况下，OpenAPI可以驱动一个模拟服务器，该服务器根据您的描述发布API。这些模拟API可以根据规范中的模式以及规范中代码的具体示例进行响应。这样，您的内部团队可以在API完全构建之前开始，并允许外部开发人员测试API的使用，而无需向服务器发送垃圾邮件（或在获得经过身份验证的访问之前）。我们对OpenAPI的最早使用之一是生成本机代码绑定。在我们的例子中，我们为前端生成TypeScript绑定以与后端交互。这将API学习过程从代码和文档转移到IDE中。我们可以依靠编辑器向我们展示各种API的内容，包括正确的类型，而不是查看服务器代码来弄清楚它是如何工作的。发布API的OpenAPI规范允许开发人员使用代码探索技术（如果愿意，可以使用Vim）来了解它。OPENAPI3.0OpenAPI项目在一年多前发布了3.0版。它包括一些非常酷但仍未得到充分利用的功能。最重要的是，它扩展了描述API的能力。很高兴看到OpenAPI在后续版本中增强了此功能。3.0版还引入了两个很酷的新元数据：LINKS和CALLBACKS。LINKS（链接）通常，一个API调用的结果可以用作另一个API调用的输入。您甚至可能见过在其响应主体中包含文本链接的API。OpenAPI的链接功能添加了描述不同API之间链接的静态元数据，以及如何将一个API的输出用作另一个API的输入。很高兴看到更多使用链接的OpenAPI文档和更好的指定链接的工具。CALLBACKS注册webhook时，您通常将URL作为字符串传递，然后服务将调用API。OpenAPI3.0允许您描述回调的签名及其应具有的参数。再次强调，脱离文档，通过代码发现问题，对开发者很有帮助。OpenAPI的更多采用减轻了API创建者的负担，并试图有效地教育他们的用户，但是，当它允许开发人员不仅学得更好，而且学得更快时，它是最有效的。OpenAPI可以做更多的工作来专注于培训开发人员使用的机器，而不是开发人员本身。例如，考虑分页。以下是GoogleCalendarAPI如何教用户翻阅日历事件：输入：pageToken：指定要返回哪个结果页面的令牌输出：nextPageToken：用于访问此结果的下一页的令牌。如果没有进一步的结果可用，则省略，在这种情况下提供nextSyncToken如果您仔细阅读，您会看到我们应该从nextPageToken获取输出并将其插入到每个后续调用的pageToken输入中，但这种语义无法在OpenAPI中表达（或谷歌专有的发现文档格式）。总结如果您已经构建了一个API或正在构建一个新API，请开始使用API描述规范。OpenAPI是一个越来越受欢迎的选择，但如果这对您不起作用，还有其他选项可供选择。您越能远离人迹罕至的地方，您就越能发现工具或生态系统的好处。可见，要构建更智能的API，拥有良好的API编写规范是非常重要的。由于国内API市场产品众多，但功能参差不齐，很难找到一款全面稳定的。最近发现一个新工具：提供API研发管理服务的EOLINKER，文档编写规则很详细，页面也很清晰。最重要的是它支持读取代码注释生成文档，还支持零代码API测试。对API管理、监控等方面感兴趣的朋友可以自行学习！https://www.eolinker.com如何开始使用OpenAPI（或类似的文档规范）描述API的过程是有争议的选择。对于契约优先理论，API规范应该是API项目的起点，并且有一些常见的Web框架工具可以从代码中提取规范（在某些情况下通过附加注释或备注辅助）。是contractfirst还是codefirst，真的要看你自己开发的时候的流程。对于较大的组织，合同优先可能是明确让服务器和客户端团队在同一页面上的正确方法。在编写服务器代码时，客户端团队可以针对自动生成的模拟进行编写。对于客户端和服务器一起开发的项目，或者API是产品本身的项目，代码就足够了。只有在这些情况下，您才能从常见的Web框架中获取OpenAPI文档（在某些情况下借助附加注释）。现在您已经有了API描述，您应该做的最重要的事情就是发布它。发布它，并保持最新。充分利用内部使用：生成服务器缓存和本机代码，构建自动化模拟，并生成详细文档。但是通过发布API文档，您可以了解开发人员用来处理API的工具。他们今天可以生成的示例、模拟测试意味着开发人员可以花更少的时间学习API的细节，而花更多的时间进行构建。随着OpenAPI及其工具生态系统的发展，API的作用也变得更加全面，因为它们使用的框架和平台变得更加智能。原标题：Transposit创始人兼首席执行官AdamLeventhal使用OpenAPI为哑机构建智能API
