명령행을 사용하여 래퍼 API 사양 및 Postman 컬렉션 생성

블록체인 앱 빌더를 사용하여 필터링된 토큰 및 계정/ID 엔드포인트 사양 파일과 일치하는 Postman 컬렉션을 생성할 수 있습니다.

wrapper-api-endpoints-config Hardhat 태스크는 배포된 계약 아티팩트 또는 ABI 파일에서 엔드포인트 구성 파일과 Postman 모음을 생성합니다. Postman 작업은 ORDS Swagger/OpenAPI 문서와 결합된 API 정의를 통합할 수도 있습니다.

전제 조건

• 아티팩트를 사용하려는 경우 프로젝트의 종속성을 설치하고 컴파일합니다.
• 래퍼 API 플러그인 및 해당 작업이 hardhat.config.ts 파일에 구성되어 있는지 확인합니다.
• 토큰 및 계정 계약 아티팩트 또는 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에 의해 표시되는 메소드 및 경로를 선택하거나 세분화할 수 있도록 생성된 끝점 구성을 검토합니다.

래퍼 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는 토큰 메소드를 계정 또는 ID 메소드와 혼합할 수 없습니다. 단계는 작성된 순서대로 실행됩니다. 이러한 동작을 염두에 두고 시퀀스 및 Failure 처리를 설계합니다. 그런 다음 다음 다음 예와 같이 편집된 구성을 사용하여 모음을 생성합니다.

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

문제 해결

조건	해결
작업을 찾을 수 없습니다.	프로젝트에 래퍼 API 플러그인이 설치되어 있고 hardhat.config.ts 파일에 구성되어 있는지 확인합니다.
아티팩트 또는 ABI 파일을 찾을 수 없음	--artifact 옵션을 사용할 때 프로젝트를 컴파일하거나 --artifact 또는 --abi 옵션으로 전달된 경로를 수정합니다.
ORDS 끝점이 누락되었습니다.	유효한 JSON에 대한 --ords-swagger 경로 지점 및 소스에 지원되는 GET 작업이 포함되어 있는지 확인합니다.
결합된 API 검증 실패	이름, 경로, 단계, 필수 입력 및 매핑이 있는지 확인합니다. 참조된 모든 메소드가 동일한 토큰 또는 계정/ID 구성에 속하는지 확인하십시오.