使用命令行生成包装 API 规范和 Postman 集合

您可以使用区块链应用程序构建器创建筛选的令牌和账户/身份端点规范文件以及匹配的 Postman 集合。

wrapper-api-endpoints-config Hardhat 任务从部署的合同对象或 ABI 文件生成端点配置文件和 Postman 集合。Postman 任务还可以包含 ORDS Swagger/OpenAPI 文档和组合 API 定义。

先决条件

• 如果计划使用构件，请安装项目的相关项并进行编译。
• 确保在 hardhat.config.ts 文件中配置了 Wrapper API 插件及其任务。
• 标识令牌，并在适用时标识账户合同构件或 ABI 文件。

生成端点配置

从预打包的合同项目的根目录运行以下命令。将示例路径和名称替换为项目中的路径。

要为要公开的每个合同目标生成端点配置文件，请运行以下命令。

npx hardhat generate:wrapper-api-endpoints-config \
  --artifact artifacts/contracts/Token.sol/Token.json \
  --out generated/wrapper-api/token-endpoints.json

npx hardhat generate:wrapper-api-endpoints-config \
  --artifact artifacts/contracts/Account.sol/Account.json \
  --out generated/wrapper-api/account-endpoints.json

要改为从 ABI 文件开始，请将 --artifact 替换为 --abi，如以下示例中所示。

npx hardhat generate:wrapper-api-endpoints-config \
  --abi ./abi/Token.json \
  --out generated/wrapper-api/token-endpoints.json

请先复核生成的端点配置，以便您可以选择或细化包装 API 公开的方法和路径。

生成 Wrapper API Postman 集合

将一个或多个端点配置文件作为逗号分隔值传递，如以下示例中所示。

npx hardhat generate:wrapper-api-postman-collection \
  --inputs generated/wrapper-api/token-endpoints.json,generated/wrapper-api/account-endpoints.json \
  --out generated/wrapper-api/wrapper-api.postman.collection.json

将生成的集合导入 Postman，并使用已部署包装 API 的 URL 和身份证明填充其环境变量。

包括 ORDS Swagger/OpenAPI 文件

可选的 --ords-swagger 参数接受 ORDS Swagger/OpenAPI JSON 文件。其 GET 操作将添加到生成的 Postman 集合中的 ORDS Endpoints 文件夹下，并在生成的配置中注册为 ORDS 后端覆盖。

npx hardhat generate:wrapper-api-postman-collection \
  --inputs generated/wrapper-api/token-endpoints.json,generated/wrapper-api/account-endpoints.json \
  --ords-swagger ./api/ords.swagger.json \
  --out generated/wrapper-api/wrapper-api.postman.collection.json

使用有效的 JSON Swagger/OpenAPI 文档。此命令未部署该文件；它是用于构建包装 API 和 Postman 资产的输入。

定义组合 API

组合 API 通过一个 POST 端点按顺序运行多个合同方法。首先，生成端点配置。然后，向该配置中添加一个 combinedApis 项，如以下示例中所示。

{
  "combinedApis": [
    {
      "name": "createAccountWithRole",
      "path": "createAccountWithRole",
      "httpMethod": "POST",
      "inputs": {
        "required": ["account", "role", "userId"]
      },
      "steps": [
        { "method": "createAccount", "args": ["userId"] },
        { "method": "addRole", "args": ["account", "role"] }
      ],
      "mappings": {
        "createAccount": { "userId": "request.userId" },
        "addRole": {
          "account": "request.account",
          "role": "request.role"
        }
      }
    }
  ]
}

将此片段与生成的配置合并；不要替换其生成的端点内容。使用合同中的实际 ABI 方法名称和参数名称。请求主体将指定的输入作为顶层字段提供，例如：account、role 和 userId。它不使用有效负载包装器。

所有步骤必须属于同一目标配置。组合的 API 不能将令牌方法与账户或身份方法混合。步骤按编写顺序运行。设计顺序和失败处理时要考虑该行为。然后，使用编辑后的配置生成集合，如以下示例所示。

npx hardhat generate:wrapper-api-postman-collection \
  --inputs generated/wrapper-api/account-endpoints.json \
  --out generated/wrapper-api/account-wrapper-api.postman.collection.json

故障排除

条件	解决方法
找不到任务	检查项目是否在 hardhat.config.ts 文件中安装并配置了包装 API 插件。
找不到构件或 ABI 文件	使用 --artifact 选项编译项目，或者更正传递给 --artifact 或 --abi 选项的路径。
缺少 ORDS 端点	验证 --ords-swagger 路径指向有效的 JSON 并且源包含支持的 GET 操作。
组合 API 验证失败	确保存在名称、路径、步骤、所需输入和映射。验证所有引用的方法是否都属于同一标记或账户/身份配置。