OpenAPI
OpenAPI(OpenAPI Specification,简称 OAS)是以机器可读方式描述 HTTP API 的开放标准:服务有哪些路径和方法、接受哪些参数、返回什么,以及如何传递密钥。文档用 JSON 或 YAML 编写,人和程序都能在无需接触源代码的情况下,通过它理解这个 API。
标准的由来
该标准源自 2011 年首次发布的 Swagger Specification。2015 年,Swagger 2.0 被捐赠给 OpenAPI Initiative(隶属 Linux Foundation 的开放项目),自 2016 年起,该规范以 OpenAPI 之名持续发展。3.0 版发布于 2017 年,3.1 版发布于 2021 年 2 月;最新的版本系列是 3.2(3.1 规范)。
文档描述什么
servers——API 的基础 URL;paths——路径和方法:每个操作都有自己的operationId、简短的summary、带位置的参数(in:query、path、header),以及按状态码划分的响应;components.schemas——对象结构(3.1 中基于 JSON Schema 2020-12);components.securitySchemes——认证方式,例如请求头中的密钥:type: apiKey、in: header。
下面是 Genesis API 规范的节选,包含资金费率操作和密钥方案:
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/funding/rates": {
"get": {
"operationId": "getFundingRates",
"summary": "Funding rates",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query", "required": false,
"schema": { "type": "string" } }
]
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": { "type": "apiKey", "in": "header",
"name": "X-API-Key" }
}
}
}
以 x- 开头的字段是规范扩展:x-genesis-plans 列出包含该操作的套餐。
规范有什么用
该标准列出的用途包括:生成文档、生成多种语言的客户端和服务端,以及测试。对 AI 智能体来说,规范就是一套现成的工具集:带有 operationId、描述和参数结构的操作,可以直接对应到函数调用(function calling)或 MCP 服务器的一个工具。
Genesis API 中的 OpenAPI
Genesis API 规范位于 genesisarbitrage.com/openapi.json:OpenAPI 3.1,共 37 个操作,密钥放在 X-API-Key 请求头中(认证)。它也可以被自动发现:genesisarbitrage.com 上由 RFC 9727 定义的 /.well-known/api-catalog 文件,通过 service-desc 链接指向它。如何把规范接入智能体,见面向 AI 智能体的 Genesis API。
另请参阅:REST API、JSON、API endpoint、面向 AI 智能体的加密货币市场数据。
常见问题
Swagger 和 OpenAPI 是同一回事吗?
它们是同一个标准的两个名称:自 2016 年起,Swagger Specification 以 OpenAPI 之名发展。2.0 版仍以 Swagger 2.0 发布,从 3.0 起则以 OpenAPI Specification 发布。
有了规范还需要 SDK 吗?
对 Genesis API 不需要:每个请求都是带一个请求头的 GET,任何 HTTP 客户端都能用。如果你想要带类型的方法,可以根据规范生成客户端。