ACXV API Schema (英语)

ACXV API的机器可读合同,由 Rust 类型生成 执行。 两件艺术品一起从同一个承诺中运出 所以他们不能 他们对API的描述有不同意见:

openapi.json 是从与 schema.json这样 其中的每一个计划都是2020-12年草案,这就是为什么该文件的目标是3.1 而不是3.0,他们的方言不能表达这些形状. 标记终点 x-internal 捆绑中缺少 OpenAPI 文档,以及 只使用类型.

npm install @across-protocol/acxv-api-schema          # tracks master
npm install @across-protocol/acxv-api-schema@staging  # tracks staging

每个出版的版本是 0.1.0-<channel>.<commit>。如果 你需要一份无法移动的合约.

输入的 HTTP 客户端

openapi-fetch 类型检查路径、方法、正体和反应:

npm install openapi-fetch
npm install -D openapi-typescript
npx openapi-typescript \
  node_modules/@across-protocol/acxv-api-schema/openapi.json \
  -o src/acxv-api.d.ts

import createClient from "openapi-fetch";
import type { paths } from "./acxv-api";

const client = createClient<paths>({
  baseUrl: "https://acxv.example.com",
  headers: { "X-API-Key": process.env.ACXV_API_KEY ?? "" },
});

// `body` is checked against SubmitOrderRequest; `data` is SubmitOrderResponse.
const { data, error } = await client.POST("/submit", { body: order });

认证头因终点而异—— /submit 带 X-API-Key中继器 结束点 X-Relayer-Key 加减 X-Auth-Message 编号 : X-Auth-Signature 双人 每个行动 security 需要的块名称,以及 components.securitySchemes 将这些名称映射到信头.

运行时间验证

对照 schema.json,它覆盖事件和 WebSocket 框架 OpenAPI 无法表达 :

import Ajv2020 from "ajv/dist/2020";
import schema from "@across-protocol/acxv-api-schema";

// `Ajv2020`, not the default `ajv` export: the bundle declares draft 2020-12 and
// the default build only carries the draft-07 meta-schema.
const ajv = new Ajv2020({ schemas: [schema] });
const validateResult = ajv.getSchema(
  `${schema.$id}#/$defs/RelayerResultResponse`,
);

if (!validateResult?.(frame)) {
  throw new Error(ajv.errorsText(validateResult?.errors));
}

无客户端类型

npm install -D json-schema-to-typescript
npx json2ts \
  --unreachableDefinitions \
  -i node_modules/@across-protocol/acxv-api-schema/schema.json \
  -o src/acxv-schema.d.ts

import type { SubmitOrderRequest, SubmitOrderResponse } from "./acxv-schema";

推荐参考文献

npx @redocly/cli preview-docs node_modules/@across-protocol/acxv-api-schema/openapi.json

每次部署都提供自己的副本—— GET /openapi.json 用于文档 财务报告和审定财务报表 GET /docs 用于提供页面, 两者都未经认证。 这些字节是 合同,部署实际上是运行, 这是权威的答案 当一个出版的文物 和现场服务 似乎不同意.

直接看文物

import schema from "@across-protocol/acxv-api-schema";
import openapi from "@across-protocol/acxv-api-schema/openapi.json";

// Endpoint metadata, keyed "METHOD /path", including the admin surface.
const submit = schema["x-endpoints"]["POST /submit"];
console.log(submit.requestBody.content["application/json"].schema.$ref);

// The same endpoint as an OpenAPI operation.
console.log(openapi.paths["/submit"].post.operationId); // "submitOrder"

WebSocket 端点在下方携带框架图 x-websocket 两者 文物,因为OpenAPI对其没有本土代表. HTTP 软件 为这些行动记录的答复 101 升级.