OpenAPI Specification¶
OpenAPI is a specification format for REST APIs. This format is supported by several tools, such as Swagger UI which allows you to browse a specification and perform API calls from your browser. Several code generators also exist to generate API libraries for various programming languages.
Shell RPCs¶
The node provide some RPCs which are independent of the protocol. Their OpenAPI specification can be found at:
Hangzhou RPCs¶
The OpenAPI specification for RPCs which are specific to the Hangzhou (PtHangz2)
protocol can be found at:
The OpenAPI specification for RPCs which are related to the mempool and specific to the Hangzhou protocol can be found at:
How to Generate¶
To generate the above files, run the src/bin_openapi/generate.sh script
from the root of the Tezos repository.
It will start a sandbox node, activate the protocol,
get the RPC specifications from this node and convert them to OpenAPI specifications.
To generate the OpenAPI specification for the RPCs provided by a specific protocol, update the following variables in src/bin_openapi/generate.sh:
`sh
protocol_hash=ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK
protocol_parameters=src/proto_alpha/parameters/sandbox-parameters.json
protocol_name=alpha
`
For protocol_hash, use the value defined in TEZOS_PROTOCOL.
How to Test¶
You can test OpenAPI specifications using Swagger Editor
to check for syntax issues (just copy-paste rpc-openapi.json into it or open
it from menu File > Import file).
You can run Swagger UI to get an interface
to browse the API (replace xxxxxx with the directory where rpc-openapi.json is,
and rpc-openapi.json by the file you want to browse):
docker pull swaggerapi/swagger-ui
docker run -p 8080:8080 -e SWAGGER_JSON=/mnt/rpc-openapi.json -v xxxxxx:/mnt swaggerapi/swagger-ui
Then open it in your browser.