chore: add open api spec into the docs

docusaurus/docs/tools/tools/open_api.md

@@ -0,0 +1,94 @@
+---
+title: Open API Spec
+sidebar_position: 4
+---
+
+## OpenAPI Specification
+
+The OpenAPI spec for the Shannon protocol is autogenerated by the [Ignite CLI](https://docs.ignite.com/).
+
+The raw file can be found at [poktroll/blob/main/docs/static/openapi.yml](https://github.com/pokt-network/poktroll/blob/main/docs/static/openapi.yml).
+
+## Swagger UI
+
+This spec for Shannon Beta TestNet may also be viewed at [shannon-testnet-grove-api.beta.poktroll.com](https://shannon-testnet-grove-api.beta.poktroll.com).
+
+## Re-generating the OpenAPI Spec
+
+You can re-generate the OpenAPI spec by running the following command:
+
+```bash
+make ignite_openapi_gen_docker
+```
+
+## `Cosmos` REST API vs `CometBFT` RPC
+
+### External Resources
+
+:::warning
+
+We are not going to dive into a discussion of REST vs RPC HTTP APIs here, but will provide minimal context.
+
+:::
+
+You can read about the general differences between REST and RPC APIs [here](https://www.smashingmagazine.com/2016/09/understanding-rest-and-rpc-for-http-apis/).
+
+The `CometBFT` RPC Specification can be found [here](https://docs.cometbft.com/v0.34/rpc/).
+
+The `Cosmos SDK` REST API Specification can be found [here](https://docs.cosmos.network/api).
+
+### `Cosmos` - Example command to check accounts
+
+```bash
+curl -X 'GET' 'https://shannon-testnet-grove-api.beta.poktroll.com/cosmos/auth/v1beta1/accounts' -H 'accept: application/json' | jq
+```
+
+### `Cosmos` - Example command to check node status
+
+```bash
+curl -X 'GET' 'https://shannon-testnet-grove-api.beta.poktroll.com/cosmos/base/node/v1beta1/status' -H 'accept: application/json' | jq
+```
+
+### `CometBFT` - Example command to check node status
+
+```bash
+curl -X 'GET' 'https://shannon-testnet-grove-rpc.beta.poktroll.com/status' -H 'accept: application/json' | jq
+```
+
+## Cosmos SDK & CometBFT API Comparison
+
+- **CometBFT RPC (`26657`)** → **Independent of Cosmos SDK APIs**. Used for blockchain consensus, P2P networking, and transaction broadcasting.
+- **Cosmos SDK gRPC (`9090`)** → **The core application API**. Provides structured, high-performance blockchain state queries.
+- **Cosmos SDK REST API (`1317`)** → **A wrapper around Cosmos SDK gRPC** for frontend-friendly JSON-based queries.
+
+:::note
+
+💡 **If gRPC (`9090`) is disabled, the REST API (`1317`) will not work.**
+💡 **If CometBFT RPC (`26657`) is down, the blockchain itself may be offline, but Cosmos SDK APIs can still work if the app is running.**
+
+:::
+
+### What is it?
+
+| **Layer**                                                                   | **What is it?**                                                                                                                                                                                                                                                                                                                                                |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **CometBFT RPC** _(Independent of the Cosmos SDK gRPC and REST API)_        | A **low-level RPC interface** that interacts with the **Tendermint consensus engine**. It is **completely independent** of the Cosmos SDK gRPC and REST API. Used for network, consensus, and blockchain-related queries (**not** application state). Also used for **sending transactions** and querying blockchain state at a protocol level.                |
+| **Cosmos SDK gRPC** _(The core application-level API)_                      | A **high-performance binary API** for querying **Cosmos SDK modules**. Provides **structured access** to chain state using **protobuf messages**. Used by full nodes, wallets, and services for **efficient state access**. **🚀 All Cosmos SDK REST API requests ultimately rely on this gRPC API.**                                                          |
+| **Cosmos SDK REST API (gRPC-Gateway)** _(A wrapper around Cosmos SDK gRPC)_ | A **RESTful wrapper** around **Cosmos SDK gRPC** that translates gRPC queries into **HTTP REST endpoints**. Enables **browser-friendly** and **frontend-compatible** access to Cosmos SDK modules. Uses **JSON over HTTP** instead of binary gRPC messages. **🚀 This API depends entirely on the Cosmos SDK gRPC API and does not work if gRPC is disabled.** |
+
+### Example Ports & Commands
+
+| **Layer**                              | **Example Port** | **Example Command**                                                              | **Example Endpoint**                                                                 |
+| -------------------------------------- | ---------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **CometBFT RPC**                       | `26657`          | `sh curl -X GET 'http://localhost:26657/status' `                                | `/status`, `/net_info`, `/block`, `/broadcast_tx_commit`                             |
+| **Cosmos SDK gRPC**                    | `9090`           | `sh grpcurl -plaintext localhost:9090 list `                                     | `cosmos.auth.v1beta1.Query/Account`, `cosmos.bank.v1beta1.Query/Balance`             |
+| **Cosmos SDK REST API (gRPC-Gateway)** | `1317`           | `sh curl -X GET 'http://localhost:1317/cosmos/auth/v1beta1/accounts/{address}' ` | `/cosmos/auth/v1beta1/accounts/{address}`, `/cosmos/bank/v1beta1/balances/{address}` |
+
+---
+
+## Embedded View
+
+import OpenAPI from '@site/src/components/OpenAPI';
+import apiSpec from '@site/static/openapi.json';
+
+<OpenAPI spec={apiSpec} />