add openapi generation

Cargo.toml

@@ -3,9 +3,14 @@ name = "explorer-api"
 version = "0.2.0"
 edition = "2021"
 
+[features]
+default = []
+openapi = ["dep:anyhow", "dep:fastnear-openapi-generator", "dep:schemars"]
+
 [dependencies]
 actix-web = "4.5.1"
 actix-cors = "0.7.0"
+anyhow = { version = "1", optional = true }
 serde = { version = "1", features = ["derive"] }
 serde_json = { version = "1", features = ["raw_value"] }
 serde_with = "3.0"
@@ -21,9 +26,16 @@ near-crypto = "0.22.0"
 
 clickhouse = { version = "0.13", features = ["native-tls", "lz4", "chrono"] }
 chrono = { version = "0.4", features = ["serde"] }
+fastnear-openapi-generator = { version = "0.2.0", optional = true }
+schemars = { version = "1.2.1", optional = true }
 
 reqwest = { version = "0.12", features = ["json"] }
 base64 = "0.22.1"
 hex = "0.4.3"
 openssl-probe = "0.1.5"
 zstd = "0.13.3"
+
+[[bin]]
+name = "generate-openapi"
+path = "src/bin/generate-openapi.rs"
+required-features = ["openapi"]

README.md

@@ -3,8 +3,84 @@
 Note, this server expects the database tables from the Clickhouse
 indexer: https://github.com/fastnear/clickhouse-provider/tree/click-dist
 
+This service now owns its aggregate OpenAPI source in-repo. The checked-in
+`openapi/openapi.yaml` file is generated from the Rust DTOs and a Rust-first operation registry:
+
+`Rust DTOs -> cargo run --features openapi --bin generate-openapi -> openapi/openapi.yaml -> mike-docs split + sync -> builder-docs direct docs runtime`
+
+Generated files in `openapi/` are not hand-edit targets. This repo no longer owns per-operation
+leaf YAML files or portal presets.
+
+## OpenAPI Generation
+
+```bash
+# Regenerate the checked-in aggregate OpenAPI file
+cargo run --features openapi --bin generate-openapi
+
+# Verify the checked-in file is current
+cargo run --features openapi --bin generate-openapi -- --check
+```
+
 All endpoints are POST and accept JSON body. The base path is `/v0`.
 
+Published base URLs:
+
+- Mainnet: `https://tx.main.fastnear.com`
+- Testnet: `https://tx.test.fastnear.com`
+
+## Testnet Quickstart
+
+Representative testnet examples:
+
+```bash
+# Account history
+curl -X POST https://tx.test.fastnear.com/v0/account \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "account_id": "root.testnet",
+    "is_real_signer": true,
+    "is_success": true,
+    "limit": 20,
+    "desc": true
+  }'
+
+# Block lookup
+curl -X POST https://tx.test.fastnear.com/v0/block \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "block_id": 46562457,
+    "with_transactions": true,
+    "with_receipts": true
+  }'
+
+# Block range
+curl -X POST https://tx.test.fastnear.com/v0/blocks \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "from_block_height": 46562448,
+    "to_block_height": 46562457,
+    "limit": 10,
+    "desc": false
+  }'
+
+# Receipt lookup
+curl -X POST https://tx.test.fastnear.com/v0/receipt \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "receipt_id": "8D3YiLcKYLAeNYmshj9cVwCTX6mgeWNXux4sJQ7FUTvV"
+  }'
+
+# Transactions by hash
+curl -X POST https://tx.test.fastnear.com/v0/transactions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "tx_hashes": [
+      "Cb9GXbQVodeJsVLiK2YnBR28vkiD7y4pEFGhxMGuP33q",
+      "9ufyhaEEzmerQz1Fvt2N91ZwXCcNZVhJXhq3QzRJZgfW"
+    ]
+  }'
+```
+
 ## POST `/v0/transactions`
 
 Fetch raw transaction data by transaction hashes. Up to 20 hashes per request.