Genesis Arbitrage

Genesis Arbitrage · · 阅读约 5 分钟

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 规范)。

文档描述什么

下面是 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 客户端都能用。如果你想要带类型的方法,可以根据规范生成客户端。