Move documentation to cargo doc

.gitignore

@@ -16,3 +16,5 @@
 dump.rdb
 
 **/venv
+
+*.DS_Store*

scripts/generate_docs.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+rm -rf ./target/doc
+
+cargo doc --no-deps \
+  --workspace \
+  --open # TODO: remove

src/macros.rs

@@ -34,6 +34,7 @@ macro_rules! bail {
     };
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! api_error {
     ($msg:literal $(,)?) => {
@@ -47,6 +48,7 @@ macro_rules! api_error {
     };
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! client_error {
     ($status_code:expr, $message:expr) => {

src/main.rs

@@ -12,16 +12,33 @@ extern crate rocket_contrib;
 
 extern crate dotenv;
 
+#[doc(hidden)]
 #[macro_use]
 pub mod macros;
 
+#[doc(hidden)]
 mod cache;
+#[doc(hidden)]
 mod config;
+
+/// Models exposed by this service
+///
+/// *Important:* Names, Enums and Polymorphism
+///
+/// Every field in the structs that you will see in this documentation is **camelCased** on serialisation.
+///
+/// Enums are **SCREAMING_SNAKE_CASED** on serialization and the variant is always put into a `type` json field for polymorphic cases.
 mod models;
+#[doc(hidden)]
 mod monitoring;
+#[doc(hidden)]
 mod providers;
+
+/// Collection of all endpoints all endpoints
 mod routes;
+#[doc(hidden)]
 mod services;
+#[doc(hidden)]
 mod utils;
 
 #[cfg(test)]
@@ -34,6 +51,7 @@ use routes::active_routes;
 use std::time::Duration;
 use utils::cors::CORS;
 
+#[doc(hidden)]
 #[launch]
 fn rocket() -> _ {
     dotenv().ok();

src/models/mod.rs

@@ -1,5 +1,7 @@
+#[doc(hidden)]
 pub mod backend;
 pub mod commons;
+#[doc(hidden)]
 pub mod converters;
 pub mod service;
 

src/models/service/about.rs

@@ -1,10 +1,28 @@
 use serde::Serialize;
 
+/// About
+///
+/// <details>
+/// <summary>Sample</summary>
+///
+/// ```json
+/// {
+///   "transactionServiceBaseUrl": "https://safe-transaction.staging.gnosisdev.com/api/v1",
+///   "name": "safe-client-gateway",
+///   "version": "0.2.0-9-g17dcd40",
+///   "buildNumber": "48"
+/// }
+/// ```
+/// </details>
 #[derive(Serialize, Debug)]
 #[serde(rename_all = "camelCase")]
 pub struct About {
+    /// base URL string used for backend requests
     pub transaction_service_base_url: String,
+    /// crate name
     pub name: String,
+    /// env variable `VERSION`, defaults to crate version
     pub version: String,
+    /// Build number from github action
     pub build_number: Option<String>,
 }

src/models/service/balances.rs

@@ -13,6 +13,8 @@ pub struct Balance {
 #[derive(Serialize, Debug, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct Balances {
+    /// Aggregated fiat balance
     pub fiat_total: String,
+    /// Individual [Balance] entries for each ERC20 in the Safe
     pub items: Vec<Balance>,
 }

src/models/service/transactions/details.rs

@@ -4,6 +4,129 @@ use crate::providers::info::{SafeAppInfo, TokenInfo};
 use serde::Serialize;
 use std::collections::HashMap;
 
+/// Top level object returned by the `/v1/transactions/<details_id>` endpoint
+///
+/// <details>
+/// <summary>Sample 1: Multisig Transaction awaiting confirmation</summary>
+///
+/// ```json
+/// {
+///   "executedAt": null,
+///   "txStatus": "AWAITING_CONFIRMATIONS",
+///   "txInfo": {
+///     "type": "SettingsChange",
+///     "dataDecoded": {
+///       "method": "changeThreshold",
+///       "parameters": [
+///         {
+///           "name": "_threshold",
+///           "type": "uint256",
+///           "value": "2"
+///         }
+///       ]
+///     }
+///   },
+///   "txData": {
+///     "hexData": "0x694e80c30000000000000000000000000000000000000000000000000000000000000002",
+///     "dataDecoded": {
+///       "method": "changeThreshold",
+///       "parameters": [
+///         {
+///           "name": "_threshold",
+///           "type": "uint256",
+///           "value": "2"
+///         }
+///       ]
+///     },
+///     "to": "0x1230B3d59858296A31053C1b8562Ecf89A2f888b",
+///     "value": "0",
+///     "operation": 0
+///   },
+///   "detailedExecutionInfo": {
+///     "type": "MULTISIG",
+///     "submittedAt": 1596792600322,
+///     "nonce": 180,
+///     "safeTxHash": "0x0ef685fb7984d7314c1368497e1b0c73016066bec41f966d32f18354b88fbd46",
+///     "signers": [
+///       "0xBEA2F9227230976d2813a2f8b922c22bE1DE1B23",
+///       "0x37e9F140A9Df5DCBc783C6c220660a4E15CBFe72",
+///       "0xA3DAa0d9Ae02dAA17a664c232aDa1B739eF5ae8D",
+///       "0xF2CeA96575d6b10f51d9aF3b10e3e4E5738aa6bd",
+///       "0x65F8236309e5A99Ff0d129d04E486EBCE20DC7B0"
+///     ],
+///     "confirmationsRequired": 3,
+///     "confirmations": [
+///       {
+///         "signer": "0xBEA2F9227230976d2813a2f8b922c22bE1DE1B23",
+///         "signature": "0x1b01f3d79a50576e82d1da31810c0313bed9b76b016e1d9c6216512b2c7e53bb70df8163e568ca8ec1b8c7e7ef0a8db52d6ab2b7f47dc51c31729dd064ce375b1c"
+///       }
+///     ]
+///   },
+///   "txHash": null
+/// }
+/// ```
+/// </details>
+///
+///
+/// <details>
+/// <summary>Sample 2: Ethereum transaction</summary>
+///
+/// ```json
+/// {
+///   "executedAt": 1596719563000,
+///   "txStatus": "SUCCESS",
+///   "txInfo": {
+///     "type": "Transfer",
+///     "sender": "0x938bae50a210b80EA233112800Cd5Bc2e7644300",
+///     "recipient": "0x1230B3d59858296A31053C1b8562Ecf89A2f888b",
+///     "direction": "INCOMING",
+///     "transferInfo": {
+///       "type": "ETHER",
+///       "value": "50000000000000"
+///     }
+///   },
+///   "txData": null,
+///   "detailedExecutionInfo": null,
+///   "txHash": "0x70b3c7f81a49f270fe86673f6c08beecfee384a89ef8b0869e46584905d4ecc2"
+/// }
+/// ```
+/// </details>
+///
+///
+/// <details>
+/// <summary>Sample 3: Settings change</summary>
+///
+/// ```json
+///     {
+///       "id": "multisig_0x57d94fe21bbee8f6646c420ee23126cd1ba1b9a53a6c9b10099a043da8f32eea",
+///       "timestamp": 1595429831000,
+///       "txStatus": "SUCCESS",
+///       "txInfo": {
+///         "type": "SettingsChange",
+///         "dataDecoded": {
+///           "method": "addOwnerWithThreshold",
+///           "parameters": [
+///             {
+///               "name": "owner",
+///               "type": "address",
+///               "value": "0xA3DAa0d9Ae02dAA17a664c232aDa1B739eF5ae8D"
+///             },
+///             {
+///               "name": "_threshold",
+///               "type": "uint256",
+///               "value": "2"
+///             }
+///           ]
+///         }
+///       },
+///       "executionInfo": {
+///         "nonce": 135,
+///         "confirmationsRequired": 2,
+///         "confirmationsSubmitted": 2
+///       }
+///     }
+/// ```
+/// </details>
 #[derive(Serialize, Debug, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct TransactionDetails {

src/models/service/transactions/requests.rs

@@ -7,6 +7,29 @@ pub struct ConfirmationRequest {
     pub signed_safe_tx_hash: String,
 }
 
+/// MultisigTransactionRequest
+///
+/// <details>
+/// <summary>Example body of MultisigTransactionRequest for submitting a Cancellation Transaction</summary>
+///
+/// ```json
+/// {
+///   "to": "0xBe8C10Dbf4c6148f9834C56C3331f8191f355552",
+///   "value": "0",
+///   "data": "0x",
+///   "nonce": "39",
+///   "operation": 0,
+///   "safeTxGas": "0",
+///   "baseGas": "0",
+///   "gasPrice": "0",
+///   "gasToken": "0x0000000000000000000000000000000000000000",
+///   "refundReceiver": "0x0000000000000000000000000000000000000000",
+///   "safeTxHash": "61b0acaeae49e74306536c3371cd80bb46aeb5732859b6ffd776ad24e2d57f8e",
+///   "sender": "0xBe8C10Dbf4c6148f9834C56C3331f8191f355552",
+///   "signature": "a519dd9aa226a5f6f1816035af85d43d834c3284912574bef0c04aaff1f21004602a5339da424cf53de9aac068f67a3417f3cba40e3049637ae901b6f345b4ac1b"
+/// }
+/// ```
+/// </details>
 #[derive(Serialize, Deserialize, Debug, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct MultisigTransactionRequest {