Better API docs

Author: m30m

apps/fortuna/src/api/explorer.rs

@@ -20,7 +20,7 @@ pub struct ExplorerQueryParams {
     #[param(value_type = Option<String>, example = "2023-10-01T00:00:00Z")]
     pub min_timestamp: Option<DateTime<Utc>>,
     /// Only return logs that are older or equal to this timestamp.
-    #[param(value_type = Option<String>, example = "2023-10-01T00:00:00Z")]
+    #[param(value_type = Option<String>, example = "2033-10-01T00:00:00Z")]
     pub max_timestamp: Option<DateTime<Utc>>,
     /// The query string to search for. This can be a transaction hash, sender address, or sequence number.
     pub query: Option<String>,
@@ -31,12 +31,14 @@ pub struct ExplorerQueryParams {
 
 const LOG_RETURN_LIMIT: u64 = 1000;
 
+/// Returns the logs of all requests captured by the keeper.
+///
+/// This endpoint allows you to filter the logs by a specific chain ID, a query string (which can be a transaction hash, sender address, or sequence number), and a time range.
+/// This is useful for debugging and monitoring the requests made to the Entropy contracts on various chains.
 #[utoipa::path(
     get,
     path = "/v1/logs",
-    responses(
-    (status = 200, description = "Entropy request logs", body = Vec<RequestStatus>)
-    ),
+    responses((status = 200, description = "A list of Entropy request logs", body = Vec<RequestStatus>)),
     params(ExplorerQueryParams)
 )]
 pub async fn explorer(

apps/fortuna/src/command/run.rs

@@ -41,6 +41,7 @@ pub async fn run_api(
     schemas(
     crate::api::GetRandomValueResponse,
     crate::history::RequestStatus,
+    crate::history::RequestEntryState,
     crate::api::Blob,
     crate::api::BinaryEncoding,
     )
@@ -242,7 +243,6 @@ async fn setup_chain_state(
     {
         return Err(anyhow!("The current hash chain for chain id {} has configured commitments for sequence numbers greater than the current on-chain sequence number. Are the commitments configured correctly?", &chain_id));
     }
-    tracing::info!("latest metadata: {:?}", latest_metadata);
 
     provider_commitments.push(Commitment {
         seed: latest_metadata.seed,

apps/fortuna/src/history.rs

@@ -11,10 +11,13 @@ use {
 };
 
 #[derive(Clone, Debug, Serialize, ToSchema, PartialEq)]
+#[serde(tag = "state", rename_all = "kebab-case")]
 pub enum RequestEntryState {
     Pending,
     Completed {
         reveal_block_number: u64,
+        /// The transaction hash of the reveal transaction.
+        #[schema(example = "0xfe5f880ac10c0aae43f910b5a17f98a93cdd2eb2dce3a5ae34e5827a3a071a32", value_type = String)]
         reveal_tx_hash: TxHash,
     },
     Failed {
@@ -24,13 +27,22 @@ pub enum RequestEntryState {
 
 #[derive(Clone, Debug, Serialize, ToSchema, PartialEq)]
 pub struct RequestStatus {
+    /// The chain ID of the request.
+    #[schema(example = "ethereum", value_type = String)]
     pub chain_id: ChainId,
+    #[schema(example = "0x6cc14824ea2918f5de5c2f75a9da968ad4bd6344", value_type = String)]
     pub provider: Address,
     pub sequence: u64,
+    #[schema(example = "2023-10-01T00:00:00Z", value_type = String)]
     pub created_at: DateTime<chrono::Utc>,
+    #[schema(example = "2023-10-01T00:00:05Z", value_type = String)]
     pub last_updated_at: DateTime<chrono::Utc>,
     pub request_block_number: u64,
+    /// The transaction hash of the request transaction.
+    #[schema(example = "0x5a3a984f41bb5443f5efa6070ed59ccb25edd8dbe6ce7f9294cf5caa64ed00ae", value_type = String)]
     pub request_tx_hash: TxHash,
+    /// This is the address that initiated the request.
+    #[schema(example = "0x78357316239040e19fc823372cc179ca75e64b81", value_type = String)]
     pub sender: Address,
     pub state: RequestEntryState,
 }

apps/fortuna/src/lib.rs

@@ -3,7 +3,6 @@ pub mod chain;
 pub mod command;
 pub mod config;
 pub mod eth_utils;
+pub mod history;
 pub mod keeper;
 pub mod state;
-
-pub mod history;