@ blockscout/ api 类型
通过 Blockscout OpenAPI 规格生成的脚本类型 openapi 类型标记数字 :
- 缩写 (单位:千美元)
schemas, (中文(简体) ),operations, (中文(简体) ),paths)——推荐的入门点;平坦地查看被合并的光谱,横跨每一个链条类型. 见 使用量 - 合并 – 从下方所有规格的每个计划,路径和操作组合到一个命名空间(对于在运行时处理任何链式类型的通用前端);参见 合并计划
- 公开Api ——默认公开 API(
BlockScoutWeb.Specs.Public,没有CHAIN_TYPE(中文(简体) ) - 隐私Api - 账户 API(
BlockScoutWeb.Specs.Private(中文(简体) ) - 链命名空间 特定链式公共API(
CHAIN_TYPE设置; 匹配 生成- swagger.yml(中文(简体) )
建造文物(openapi/, (中文(简体) ), dist/) 被给定; 运行 npm run build 复制后.
先决条件
- Elixir / 混音 blockscout repo 根 (编译)
block_scout_web应用) - 节点.js 18+(用于
openapi-typescript(中文(简体) )
生成
从此目录 :
npm install
npm run build
build 运行 :
generate:spec—— 说mix openapi.spec.yaml用于公共、私人和每一链型generate:types—— 说openapi-typescript将匹配的文件写入到dist/
使用量
简称( 建议)
3个顶级出口将最常见的视线固定在合并的光谱上,所以你从来没有通过索引 components["schemas"] 或者说 ["responses"][200]["content"]["application/json"] 手边。 优先供日常使用:
import type { schemas, operations, paths } from "@blockscout/api-types";
// `schemas` — a model by name (merged across all chains; chain-specific props optional).
type Transaction = schemas["Transaction"];
// `operations` — keyed by short operationId, with `json` / `params` / `requestBody`.
type TxJson = operations["TransactionController.transaction"]["json"];
type TxParams = operations["TransactionController.transaction"]["params"];
type EthCallBody = operations["EthController.eth_call"]["requestBody"];
// `paths` — the 200 `application/json` body keyed by path, then HTTP method.
type Blocks = paths["/api/v2/blocks"]["get"];
注释:
- 操作ID被缩短 ——控制器模块前缀(
BlockScoutWeb.API.V2., (中文(简体) ),BlockScoutWeb.Account.API.V2., (中文(简体) ),BlockScoutWeb.API.Legacy.)被剥去,所以BlockScoutWeb.API.V2.TransactionController.transaction变成TransactionController.transaction。 。 。 . json这是200application/json反应机构;params是请求query编号 :path参数;requestBody这是application/json请求机构(never没有终点.paths只披露 HTTP 方法, 即实际定义的终点; 缺少方法, 而不是never。 。 。 .- 三者皆从
merged,所以它们已经跨越了每一个链的类型。 到达merged/ 在下方的每个链命名空间, 只有当您需要的东西不覆盖时( 非200 响应, 响应头, 原始路径项目) .
合并计划
上面的简称是建立在 合并 命名空间——每个从所有光谱组合出来的计划,路径,和操作,因此一个通用前端可以在运行时间从一个单一类型宇宙处理任何链型. 导入 merged 当您需要检查时, 短手不暴露( 非200 个响应、 响应头、 原始路径项) :
import type { merged } from "@blockscout/api-types";
// Includes the public base plus `arbitrum?`, `zksync?`, blob fields, etc. — all optional.
type Transaction = merged.components["schemas"]["Transaction"];
// Paths/operations are merged too, referencing the merged models:
type Tx = merged.paths["/api/v2/transactions/{transaction_hash_param}"]["get"]["responses"][200];
单相命名空间
类型还按包项中的 spec 名称分组:
import type { publicApi, privateApi, arbitrum, optimismCelo } from "@blockscout/api-types";
type AddressResponse = publicApi.components["schemas"]["AddressResponse"];
type GetAddressParams =
publicApi.paths["/api/v2/addresses/{address_hash_param}"]["get"]["parameters"];
type ArbitrumPath = arbitrum.paths[keyof arbitrum.paths];
publicApi 编号 : privateApi 避免 TypeScript 保留单词(public, (中文(简体) ), private) (中文(简体) ). optimism-celo 导出为 optimismCelo (标识符中的连字符无效)
链型
与 .github/workflows/generate-swagger.yml 通过 scripts/chain-types.sh数字 :
arbitrum, (中文(简体) ), arc, (中文(简体) ), blackfort, (中文(简体) ), ethereum, (中文(简体) ), filecoin, (中文(简体) ), neon, (中文(简体) ), optimism, (中文(简体) ), optimism-celo, (中文(简体) ), rsk, (中文(简体) ), scroll, (中文(简体) ), shibarium, (中文(简体) ), stability, (中文(简体) ), suave, (中文(简体) ), zetachain, (中文(简体) ), zilliqa, (中文(简体) ), zksync
当 CI 添加或删除链式时, 更新 scripts/chain-types.sh 财务报告和审定财务报表 index.ts。 。 。 .
组合图
scripts/merge-specs.mjs 将所有生成的光谱( 公共 ) —— 私人 —— 链条按字母顺序合并到 openapi/merged.yaml,用于编译 dist/merged.schema.ts (以 merged) (中文(简体) ).
合并语义 :
- 示马斯 —— 说
properties工会;required是定义 schema 的相交点, 因此链状特性是可选的 。 在一个光谱中定义的子对象保留其required(例如:.arbitrum.gas_used_for_l1需要保留时arbitrum页:1.enum数值结合(例如).transaction_types收益链专用条目). - 路径操作( O) ——跨个相通;仅链式终点(如.
/v2/arbitrum/batches页:1 共享业务已深入开展parameters与(在名称中)及其schemas结合(如enum查询参数获得链特有值). 所有操作$ref点为components.schemas,因此它们自动引用合并的模型. - 不可调和的图案形状( 如 ethereum 重新定义)
Status作为信标存储器anyOf工会,并报告为对工会的警告.