Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(rpc): OpenAPI spec #8342

Merged
merged 2 commits into from
Mar 14, 2024
+1,934 −61
Merged

feat(rpc): OpenAPI spec #8342

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
064190f
add an openapi generator
oxarbitrage Mar 11, 2024
d186d74
fix run command
oxarbitrage Mar 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 53 additions & 30 deletions Cargo.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,7 +239,7 @@ checksum = "16e62a023e7c117e27523144c5d2459f4397fcc3cab0085af8e2224f643a0193"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand All @@ -250,7 +250,7 @@ checksum = "c980ee35e870bd1a4d2c8294d4c04d0499e67bca1e4b5cefcc693c2fa00caea9"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -409,7 +409,7 @@ dependencies = [
"regex",
"rustc-hash",
"shlex",
"syn 2.0.50",
"syn 2.0.52",
"which",
]

Expand Down Expand Up @@ -805,7 +805,7 @@ dependencies = [
"heck 0.4.1",
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -1066,7 +1066,7 @@ checksum = "f46882e17999c6cc590af592290432be3bce0428cb0d5f8b6715e4dc7b383eb3"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand All @@ -1090,7 +1090,7 @@ dependencies = [
"codespan-reporting",
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand All @@ -1107,7 +1107,7 @@ checksum = "2fa16a70dd58129e4dfffdff535fb1bce66673f7bbeec4a5a1765a504e1ccd84"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -1155,7 +1155,7 @@ dependencies = [
"proc-macro2",
"quote",
"strsim 0.10.0",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand All @@ -1177,7 +1177,7 @@ checksum = "c5a91391accf613803c2a9bf9abccdbaa07c54b4244a5b64883f9c3c137c86be"
dependencies = [
"darling_core 0.20.6",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -1250,7 +1250,7 @@ checksum = "487585f4d0c6655fe74905e2504d8ad6908e4db67f744eb140876906c2f3175d"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -1546,7 +1546,7 @@ checksum = "87750cf4b7a4c0625b1529e4c543c2182106e4dedc60a2a6455e00d212c489ac"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -2500,7 +2500,7 @@ checksum = "38b4faf00617defe497754acde3024865bc143d44a86799b24e191ecff91354f"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -2935,7 +2935,7 @@ dependencies = [
"pest_meta",
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -2976,7 +2976,7 @@ checksum = "266c042b60c9c76b8d53061e52b2e0d1116abc57cefc8c5cd671619a56ac3690"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -3077,7 +3077,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a41cf62165e97c7f814d2221421dbb9afcbcdb0a88068e5ea206e19951c2cbb5"
dependencies = [
"proc-macro2",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -3200,7 +3200,7 @@ dependencies = [
"prost",
"prost-types",
"regex",
"syn 2.0.50",
"syn 2.0.52",
"tempfile",
"which",
]
Expand All @@ -3215,7 +3215,7 @@ dependencies = [
"itertools 0.11.0",
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -3923,7 +3923,7 @@ checksum = "7eb0b34b42edc17f6b7cac84a52a1c5f0e1bb2227e997ca9011ea3dd34e8610b"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -4008,7 +4008,20 @@ dependencies = [
"darling 0.20.6",
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
name = "serde_yaml"
version = "0.9.32"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8fd075d994154d4a774f95b51fb96bdc2832b0ea48425c92546073816cda1f2f"
dependencies = [
"indexmap 2.2.3",
"itoa",
"ryu",
"serde",
"unsafe-libyaml",
]

[[package]]
Expand Down Expand Up @@ -4224,9 +4237,9 @@ dependencies = [

[[package]]
name = "syn"
version = "2.0.50"
version = "2.0.52"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "74f1bdc9872430ce9b75da68329d1c1746faf50ffac5f19e02b71e37ff881ffb"
checksum = "b699d15b36d1f02c3e7c69f8ffef53de37aefae075d8488d4ba1a7788d574a07"
dependencies = [
"proc-macro2",
"quote",
Expand Down Expand Up @@ -4325,7 +4338,7 @@ checksum = "a953cb265bef375dae3de6663da4d3804eee9682ea80d8e2542529b73c531c81"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -4448,7 +4461,7 @@ checksum = "5b8a1e28f2deaa14e508979454cb3a223b10b938b45af148bc0986de36f1923b"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -4632,7 +4645,7 @@ dependencies = [
"proc-macro2",
"prost-build",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand All @@ -4645,7 +4658,7 @@ dependencies = [
"proc-macro2",
"prost-build",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -4775,7 +4788,7 @@ checksum = "34704c8d6ebcbc939824180af020566b01a7c01f80641264eba0999f6c2b6be7"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand Down Expand Up @@ -4996,6 +5009,12 @@ dependencies = [
"subtle",
]

[[package]]
name = "unsafe-libyaml"
version = "0.2.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ab4c90930b95a82d00dc9e9ac071b4991924390d46cbd0dfe566148667605e4b"

[[package]]
name = "untrusted"
version = "0.7.1"
Expand Down Expand Up @@ -5207,7 +5226,7 @@ dependencies = [
"once_cell",
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
"wasm-bindgen-shared",
]

Expand Down Expand Up @@ -5241,7 +5260,7 @@ checksum = "642f325be6301eb8107a83d12a8ac6c1e1c54345a7ef1a9261962dfefda09e66"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
"wasm-bindgen-backend",
"wasm-bindgen-shared",
]
Expand Down Expand Up @@ -6029,10 +6048,14 @@ dependencies = [
"hex",
"itertools 0.12.1",
"jsonrpc",
"quote",
"regex",
"reqwest",
"serde",
"serde_json",
"serde_yaml",
"structopt",
"syn 2.0.52",
"thiserror",
"tinyvec",
"tokio",
Expand Down Expand Up @@ -6133,7 +6156,7 @@ checksum = "9ce1b18ccd8e73a9321186f97e46f9f04b778851177567b1975109d26a08d2a6"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]

[[package]]
Expand All @@ -6153,5 +6176,5 @@ checksum = "ce36e65b0d2999d2aafac989fb249189a141aee1f53c612c1f37d72631959f69"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.50",
"syn 2.0.52",
]
47 changes: 47 additions & 0 deletions book/src/user/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Zebra OpenAPI specification

The Zebra RPC methods are a collection of endpoints used for interacting with the Zcash blockchain. These methods are utilized by wallets, block explorers, web and mobile applications, and more, for retrieving and sending information to the blockchain.

While the Zebra source code and RPC methods are well-documented, accessing this information typically involves searching for each function within the [Zebra crate documentation](https://docs.rs/zebrad/latest/zebrad/#zebra-crates), which may be inconvenient for users who are not familiar with Rust development.

To address this issue, the Zebra team has created an [OpenAPI](https://www.openapis.org/) specification in the [YAML](https://en.wikipedia.org/wiki/YAML) format.

The Zebra OpenAPI specification is stored in a file named openapi.yaml, located at the root of the project. The latest version of this specification will always be available [here](https://github.com/ZcashFoundation/zebra/blob/main/openapi.yaml).

## Usage

There are several ways to utilize the specification. For users unfamiliar with OpenAPI and Swagger, simply navigate to the [Swagger Editor](https://editor.swagger.io/) and paste the specification there.

![image info](openapi1.png)

To send and receive data directly from/to the blockchain within the Swagger web app, you'll need a Zebra node with the RPC endpoint enabled.

To enable this functionality, start zebrad with a custom configuration. Generate a default configuration by running the following command:

```console
mkdir -p ~/.config
zebrad generate -o ~/.config/zebrad.toml
```

Then, add the IP address and port to the `rpc` section of the configuration:

```
[rpc]
listen_addr = "127.0.0.1:8232"
```

If you modify the address and port in the Zebra configuration, ensure to update it in the `openapi.yaml` specification as well.

Start Zebra with the following command:

```console
zebrad
```

You should now be able to send requests and receive responses within Swagger.

![image info](openapi2.png)

![image info](openapi3.png)


Binary file added book/src/user/openapi1.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added book/src/user/openapi2.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added book/src/user/openapi3.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading