OpenAPI Specification
用统一格式记录API提供什么功能、该如何调用的标准说明书
简单来说
OpenAPI Specification 是一份文档,它按照非常固定的格式,记录程序之间如何通过 API 对话——简单说就是 API 的使用说明书。拿餐厅来比喻的话,它就像一份菜单,但不是随手写的菜单,而是把菜名、食材、价格、点餐方式都按照统一格式写清楚,让任何人看到都能读出同样的意思。
这种格式为什么重要?因为读这份文档并据此行动的,不是人,而是计算机程序。人可以凭感觉理解模糊的说明,但程序做不到。用 OpenAPI Specification 写成的文档,能让不同公司、不同开发者做的程序看着同一套规则,自动弄清楚该怎么互相连接。最近,AI 智能体也开始读取这类文档,自己写出调用 API 的代码,或者找到并使用自己需要的功能。
打个比方,这就像全世界约定好统一使用同一种表格格式,而不是让每个国家的大使馆各自用不同语言做各自的申请表。这样一来,任何人只要看这份表格,就能马上明白该在哪里填什么内容。
在报道中是这样出现的
在报道中通常会出现类似"该服务公开了其 OpenAPI Specification"这样的表述。这并不是说这个服务重新开发了一个 API,而是说它把已有 API 的功能和调用方法整理成标准格式的文档并公开发布了。API 和 OpenAPI Specification 很容易混为一谈,但二者不同:API 是实际的功能本身,而 OpenAPI Specification 是描述该功能的标准化文档。
亲手试一试
在你平时使用的服务的开发者文档页面上,找一找是否有名为 openapi.json、openapi.yaml 或 swagger.json 之类的链接。如果找到了,把这个文件的地址或内容粘贴给编程助手 AI,让它"根据这份 API 规范写出调用某个特定功能的代码",你就能亲眼看到 AI 读懂文档后直接生成代码的过程。