Merge pull request #323 from hirosystems/openapi

feat: add `chainhook docs api generate` command

components/chainhook-cli/Cargo.toml

@@ -38,7 +38,7 @@ atty = "0.2.14"
 crossbeam-channel = "0.5.8"
 uuid = { version = "1.3.0", features = ["v4", "fast-rng"] }
 threadpool = "1.8.1"
-rocket_okapi = "0.8.0-rc.3"
+rocket_okapi = { version = "0.8.0-rc.3", git = "https://github.com/hirosystems/okapi.git", branch = "feat-chainhook-fixes"}
 rocket = { version = "=0.5.0-rc.3", features = ["json"] }
 
 [dependencies.rocksdb]

components/chainhook-cli/src/cli/mod.rs

@@ -3,6 +3,7 @@ use crate::config::generator::generate_config;
 use crate::config::{Config, PredicatesApi};
 use crate::scan::bitcoin::scan_bitcoin_chainstate_via_rpc_using_predicate;
 use crate::scan::stacks::scan_stacks_chainstate_via_csv_using_predicate;
+use crate::service::http_api::document_predicate_api_server;
 use crate::service::Service;
 use crate::storage::{
     get_last_block_height_inserted, get_stacks_block_at_block_height, is_stacks_block_present,
@@ -52,6 +53,9 @@ enum Command {
     /// Stacks related subcommands  
     #[clap(subcommand)]
     Stacks(StacksCommand),
+    /// Generate documentation  
+    #[clap(subcommand)]
+    Docs(DocsCommand),
 }
 
 #[derive(Subcommand, PartialEq, Clone, Debug)]
@@ -248,6 +252,22 @@ struct InitHordDbCommand {
     pub config_path: Option<String>,
 }
 
+#[derive(Subcommand, PartialEq, Clone, Debug)]
+#[clap(bin_name = "docs", aliases=&["doc"])]
+enum DocsCommand {
+    /// Generate new documentation for the predicate registration API.
+    #[clap(subcommand)]
+    #[clap(name = "api")]
+    Api(ApiDocsCommand),
+}
+
+#[derive(Subcommand, PartialEq, Clone, Debug)]
+enum ApiDocsCommand {
+    /// Generate documentation for the predicate registration API.
+    #[clap(name = "new", bin_name = "new", aliases = &["generate"])]
+    Generate,
+}
+
 pub fn main() {
     let logger = hiro_system_kit::log::setup_logger();
     let _guard = hiro_system_kit::log::setup_global_logger(logger.clone());
@@ -571,6 +591,25 @@ async fn handle_command(opts: Opts, ctx: Context) -> Result<(), String> {
                 }
             }
         },
+        Command::Docs(subcmd) => match subcmd {
+            DocsCommand::Api(api_docs_cmd) => match api_docs_cmd {
+                ApiDocsCommand::Generate => {
+                    use std::fs::File;
+                    use std::io::Write;
+                    let spec = document_predicate_api_server()
+                        .map_err(|e| format!("unable to generate API docs: {}", e))?;
+                    let mut file_path = PathBuf::new();
+                    file_path.push("openapi.json");
+                    let mut file = File::create(&file_path).map_err(|e| {
+                        format!("unable to open file {}\n{}", file_path.display(), e)
+                    })?;
+                    file.write_all(spec.as_bytes()).map_err(|e| {
+                        format!("unable to write file {}\n{}", file_path.display(), e)
+                    })?;
+                    println!("Created file openapi.json");
+                }
+            },
+        },
     }
     Ok(())
 }

components/chainhook-cli/src/service/http_api.rs

@@ -14,8 +14,7 @@ use redis::{Commands, Connection};
 use rocket::config::{self, Config, LogLevel};
 use rocket::serde::json::{json, Json, Value as JsonValue};
 use rocket::State;
-use rocket_okapi::openapi;
-use rocket_okapi::openapi_get_routes;
+use rocket_okapi::{okapi::openapi3::OpenApi, openapi, openapi_get_routes_spec};
 use std::error::Error;
 
 use crate::config::PredicatesApiConfig;
@@ -46,14 +45,7 @@ pub async fn start_predicate_api_server(
         ..Config::default()
     };
 
-    let routes = openapi_get_routes![
-        handle_ping,
-        handle_get_predicates,
-        handle_get_predicate,
-        handle_create_predicate,
-        handle_delete_bitcoin_predicate,
-        handle_delete_stacks_predicate
-    ];
+    let (routes, _) = get_routes_spec();
 
     let background_job_tx_mutex = Arc::new(Mutex::new(observer_commands_tx.clone()));
 
@@ -372,3 +364,21 @@ pub fn load_predicates_from_redis(
         .map_err(|e| format!("unable to connect to redis: {}", e.to_string()))?;
     get_entries_from_predicates_db(&mut predicate_db_conn, ctx)
 }
+
+pub fn document_predicate_api_server() -> Result<String, String> {
+    let (_, spec) = get_routes_spec();
+    let json_spec = serde_json::to_string_pretty(&spec)
+        .map_err(|e| format!("failed to serialize openapi spec: {}", e.to_string()))?;
+    Ok(json_spec)
+}
+
+pub fn get_routes_spec() -> (Vec<rocket::Route>, OpenApi) {
+    openapi_get_routes_spec![
+        handle_ping,
+        handle_get_predicates,
+        handle_get_predicate,
+        handle_create_predicate,
+        handle_delete_bitcoin_predicate,
+        handle_delete_stacks_predicate
+    ]
+}

components/chainhook-cli/src/service/mod.rs

@@ -1,4 +1,4 @@
-mod http_api;
+pub(crate) mod http_api;
 mod runloops;
 
 use crate::config::{Config, PredicatesApi, PredicatesApiConfig};

components/chainhook-sdk/Cargo.toml

@@ -32,7 +32,7 @@ reqwest = { version = "0.11", default-features = false, features = [
 ] }
 tokio = { version = "1.24", features = ["full"] }
 base58 = "0.2.0"
-schemars = { version = "0.8.10" }
+schemars = { version = "0.8.10", git = "https://github.com/hirosystems/schemars.git", branch = "feat-chainhook-fixes" }
 crossbeam-channel = "0.5.6"
 futures = "0.3.21"
 hyper = { version = "0.14.24", features = ["http1", "client"] }

components/chainhook-types-rs/Cargo.toml

@@ -12,5 +12,5 @@ serde = "1"
 serde_json = "1"
 serde_derive = "1"
 strum = { version = "0.23.0", features = ["derive"] }
-schemars = { version = "0.8.10" }
+schemars = { version = "0.8.10", git = "https://github.com/hirosystems/schemars.git", branch = "feat-chainhook-fixes" }
 hex = "0.4.3"