WIP adding derive(ToSchema)

Cargo.lock

@@ -4966,6 +4966,7 @@ dependencies = [
  "sha2 0.9.9",
  "subtle 2.5.0",
  "thiserror",
+ "utoipa",
  "zeroize",
 ]
 
@@ -6544,6 +6545,7 @@ dependencies = [
  "serde_json",
  "sha2 0.10.8",
  "time",
+ "utoipa",
 ]
 
 [[package]]
@@ -10565,18 +10567,18 @@ dependencies = [
 
 [[package]]
 name = "utoipauto"
-version = "0.1.14"
+version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "608b8f2279483be386261655b562e40877ea434eb92093c894a644fda2021860"
+checksum = "cba36db2c397c614110554a60fbb4bb97d5f8c6823775c766e6f455e37377047"
 dependencies = [
  "utoipauto-macro",
 ]
 
 [[package]]
 name = "utoipauto-core"
-version = "0.1.12"
+version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "17e82ab96c5a55263b5bed151b8426410d93aa909a453acdbd4b6792b5af7d64"
+checksum = "268d76aaebb80eba79240b805972e52d7d410d4bcc52321b951318b0f440cd60"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -10585,9 +10587,9 @@ dependencies = [
 
 [[package]]
 name = "utoipauto-macro"
-version = "0.1.12"
+version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "86b8338dc3c9526011ffaa2aa6bd60ddfda9d49d2123108690755c6e34844212"
+checksum = "382673bda1d05c85b4550d32fd4192ccd4cffe9a908543a0795d1e7682b36246"
 dependencies = [
  "proc-macro2",
  "quote",

Cargo.toml

@@ -347,7 +347,7 @@ tungstenite = { version = "0.20.1", default-features = false }
 url = "2.5"
 utoipa = "4.2"
 utoipa-swagger-ui = "7.1"
-utoipauto = "0.1"
+utoipauto = "0.2"
 uuid = "*"
 vergen = { version = "=8.3.1", default-features = false }
 walkdir = "2"

common/nym_offline_compact_ecash/Cargo.toml

@@ -20,6 +20,7 @@ rand = { workspace = true }
 thiserror = { workspace = true }
 sha2 = "0.9"
 bs58 = { workspace = true }
+utoipa = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 rayon = { workspace = true, optional = true }
 zeroize = { workspace = true, features = ["zeroize_derive"] }
@@ -63,4 +64,4 @@ par_signing = ["rayon"]
 # but given it's not done very frequently, it shouldn't be too much of a problem
 # furthermore, we can't and shouldn't dedicate the entire nym-api CPU just for verification,
 # but this feature might potentially be desirable for clients.
-par_verify = ["rayon"]
+par_verify = ["rayon"]

common/nym_offline_compact_ecash/src/common_types.rs

@@ -7,15 +7,26 @@ use crate::helpers::{g1_tuple_to_bytes, recover_g1_tuple};
 use bls12_381::{G1Projective, Scalar};
 use serde::{Deserialize, Serialize};
 use subtle::Choice;
+use utoipa::ToSchema;
 
 pub type SignerIndex = u64;
 
-#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, ToSchema)]
 pub struct Signature {
+    #[schema(value_type = G1ProjectiveSchema)]
     pub(crate) h: G1Projective,
+    #[schema(value_type = G1ProjectiveSchema)]
     pub(crate) s: G1Projective,
 }
 
+#[derive(ToSchema)]
+#[schema(title = "G1Projective")]
+pub struct G1ProjectiveSchema {
+    pub x: [u64; 6],
+    pub y: [u64; 6],
+    pub z: [u64; 6],
+}
+
 pub type PartialSignature = Signature;
 
 impl Signature {
@@ -66,9 +77,11 @@ impl Signature {
     }
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, ToSchema)]
 pub struct BlindedSignature {
+    #[schema(value_type = G1ProjectiveSchema)]
     pub(crate) h: G1Projective,
+    #[schema(value_type = G1ProjectiveSchema)]
     pub(crate) c: G1Projective,
 }
 

common/nym_offline_compact_ecash/src/lib.rs

@@ -36,7 +36,7 @@ pub mod common_types;
 pub mod constants;
 pub mod error;
 mod helpers;
-mod proofs;
+pub mod proofs;
 pub mod scheme;
 pub mod tests;
 mod traits;

common/nym_offline_compact_ecash/src/proofs/proof_withdrawal.rs

@@ -8,6 +8,7 @@ use bls12_381::{G1Projective, Scalar};
 use group::GroupEncoding;
 use itertools::izip;
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 
 #[derive(Debug, Serialize, Deserialize)]
 #[cfg_attr(test, derive(PartialEq))]
@@ -32,11 +33,15 @@ pub struct WithdrawalReqWitness<'a> {
     pub private_attributes_openings: &'a Vec<Scalar>,
 }
 
-#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+#[derive(Debug, PartialEq, Clone, Serialize, Deserialize, ToSchema)]
 pub struct WithdrawalReqProof {
+    #[schema(value_type = [u64; 4])]
     challenge: Scalar,
+    #[schema(value_type = [u64; 4])]
     response_opening: Scalar,
+    #[schema(value_type = Vec<[u64; 4]>)]
     response_openings: Vec<Scalar>,
+    #[schema(value_type = Vec<[u64; 4]>)]
     response_attributes: Vec<Scalar>,
 }
 

common/nym_offline_compact_ecash/src/scheme/coin_indices_signatures.rs

@@ -11,13 +11,15 @@ use crate::utils::{batch_verify_signatures, hash_g1};
 use bls12_381::{G1Projective, Scalar};
 use itertools::Itertools;
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 use std::borrow::Borrow;
 
 pub type CoinIndexSignature = Signature;
 pub type PartialCoinIndexSignature = CoinIndexSignature;
 
-#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, ToSchema)]
 pub struct AnnotatedCoinIndexSignature {
+    #[schema(value_type = Signature)]
     pub signature: CoinIndexSignature,
     pub index: u64,
 }

common/nym_offline_compact_ecash/src/scheme/expiration_date_signatures.rs

@@ -11,16 +11,20 @@ use crate::{constants, EncodedDate};
 use bls12_381::{G1Projective, Scalar};
 use itertools::Itertools;
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 use std::borrow::Borrow;
 
 /// A structure representing an expiration date signature.
 pub type ExpirationDateSignature = Signature;
 pub type PartialExpirationDateSignature = ExpirationDateSignature;
 
-#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, ToSchema)]
 pub struct AnnotatedExpirationDateSignature {
+    #[schema(value_type = Signature)]
     pub signature: ExpirationDateSignature,
+    #[schema(value_type = u32)]
     pub expiration_timestamp: EncodedDate,
+    #[schema(value_type = u32)]
     pub spending_timestamp: EncodedDate,
 }
 

common/nym_offline_compact_ecash/src/scheme/keygen.rs

@@ -18,6 +18,7 @@ use core::ops::{Add, Mul};
 use group::{Curve, GroupEncoding};
 use nym_pemstore::traits::{PemStorableKey, PemStorableKeyPair};
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 use zeroize::{Zeroize, ZeroizeOnDrop};
 
 #[derive(Debug, PartialEq, Clone, Zeroize, ZeroizeOnDrop)]
@@ -124,10 +125,13 @@ impl SecretKeyAuth {
     }
 }
 
-#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+#[derive(Debug, PartialEq, Clone, Serialize, Deserialize, ToSchema)]
 pub struct VerificationKeyAuth {
+    #[schema(value_type = G1ProjectiveSchema)]
     pub(crate) alpha: G2Projective,
+    #[schema(value_type = Vec<G1ProjectiveSchema>)]
     pub(crate) beta_g1: Vec<G1Projective>,
+    #[schema(value_type = Vec<G1ProjectiveSchema>)]
     pub(crate) beta_g2: Vec<G2Projective>,
 }
 

common/nym_offline_compact_ecash/src/scheme/withdrawal.rs

@@ -15,6 +15,7 @@ use crate::{constants, ecash_group_parameters, Attribute, EncodedDate, EncodedTi
 use bls12_381::{multi_miller_loop, G1Projective, G2Prepared, G2Projective, Scalar};
 use group::{Curve, Group, GroupEncoding};
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 use std::ops::Neg;
 use zeroize::{Zeroize, ZeroizeOnDrop};
 
@@ -34,10 +35,13 @@ use zeroize::{Zeroize, ZeroizeOnDrop};
 ///
 /// The struct derives `Debug` and `PartialEq` to provide debug output and basic comparison functionality.
 ///
-#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+#[derive(Debug, PartialEq, Clone, Serialize, Deserialize, ToSchema)]
 pub struct WithdrawalRequest {
+    #[schema(value_type = G1ProjectiveSchema)]
     joined_commitment_hash: G1Projective,
+    #[schema(value_type = G1ProjectiveSchema)]
     joined_commitment: G1Projective,
+    #[schema(value_type = Vec<G1ProjectiveSchema>)]
     private_attributes_commitments: Vec<G1Projective>,
     zk_proof: WithdrawalReqProof,
 }

common/ticketbooks-merkle/Cargo.toml

@@ -14,6 +14,7 @@ readme.workspace = true
 sha2 = { workspace = true }
 rs_merkle = { workspace = true }
 schemars = { workspace = true }
+utoipa = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 time = { workspace = true }
 
@@ -23,4 +24,4 @@ nym-serde-helpers = { path = "../serde-helpers", features = ["date", "base64", "
 [dev-dependencies]
 rand_chacha = { workspace = true }
 rand = { workspace = true }
-serde_json = { workspace = true }
+serde_json = { workspace = true }

common/ticketbooks-merkle/src/lib.rs

@@ -12,6 +12,7 @@ use rs_merkle::{MerkleProof, MerkleTree};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use sha2::Digest;
+use utoipa::ToSchema;
 use std::fmt::{Debug, Formatter};
 use time::Date;
 
@@ -80,7 +81,7 @@ pub struct InsertedMerkleLeaf {
     pub leaf: MerkleLeaf,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialOrd, PartialEq, Eq)]
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialOrd, PartialEq, Eq, ToSchema)]
 pub struct MerkleLeaf {
     #[schemars(with = "String")]
     #[serde(with = "nym_serde_helpers::hex")]
@@ -162,16 +163,14 @@ impl IssuedTicketbooksMerkleTree {
     }
 }
 
-#[derive(Serialize, Deserialize, JsonSchema)]
+#[derive(Serialize, Deserialize, JsonSchema, ToSchema)]
 pub struct IssuedTicketbooksFullMerkleProof {
     #[schemars(with = "String")]
     #[serde(with = "inner_proof_base64_serde")]
+    #[schema(value_type = String)]
     inner_proof: MerkleProof<Sha256>,
-
     included_leaves: Vec<MerkleLeaf>,
-
     total_leaves: usize,
-
     #[schemars(with = "String")]
     #[serde(with = "nym_serde_helpers::hex")]
     root: Vec<u8>,

nym-api/nym-api-requests/src/ecash/models.rs

@@ -116,6 +116,7 @@ pub struct BlindSignRequestBody {
 
     /// Signature on the inner sign request and the tx hash
     #[schemars(with = "PlaceholderJsonSchemaImpl")]
+    #[schema(value_type = String)]
     pub signature: identity::Signature,
 
     #[schemars(with = "PlaceholderJsonSchemaImpl")]
@@ -297,7 +298,7 @@ pub struct Pagination<T> {
     pub limit: Option<u32>,
 }
 
-#[derive(Clone, Serialize, Deserialize, Debug, JsonSchema, PartialEq)]
+#[derive(Clone, Serialize, Deserialize, Debug, JsonSchema, PartialEq, ToSchema)]
 pub struct SerialNumberWrapper(
     #[serde(with = "nym_serde_helpers::bs58")]
     #[schemars(with = "String")]
@@ -323,7 +324,7 @@ impl From<Vec<u8>> for SerialNumberWrapper {
     }
 }
 
-#[derive(Clone, Serialize, Deserialize, Debug, JsonSchema, PartialEq)]
+#[derive(Clone, Serialize, Deserialize, Debug, JsonSchema, PartialEq, ToSchema)]
 pub struct BatchRedeemTicketsBody {
     #[serde(with = "nym_serde_helpers::bs58")]
     #[schemars(with = "String")]
@@ -331,9 +332,20 @@ pub struct BatchRedeemTicketsBody {
     pub included_serial_numbers: Vec<SerialNumberWrapper>,
     pub proposal_id: u64,
     #[schemars(with = "String")]
+    #[schema(value_type = AccountIdSchema)]
     pub gateway_cosmos_addr: AccountId,
 }
 
+#[allow(dead_code)] // not dead, used in OpenAPI schema
+#[derive(ToSchema)]
+#[schema(title = "AccountId")]
+pub struct AccountIdSchema {
+    /// Account ID encoded as Bech32
+    bech32: String,
+    /// Length of the human-readable prefix of the address
+    hrp_length: usize,
+}
+
 impl BatchRedeemTicketsBody {
     pub fn make_digest<I, T>(serial_numbers: I) -> Vec<u8>
     where
@@ -424,8 +436,9 @@ impl IssuedTicketbooksForResponseBody {
 pub struct IssuedTicketbooksForResponse {
     pub body: IssuedTicketbooksForResponseBody,
 
-    /// Signature on the body    
+    /// Signature on the body
     #[schemars(with = "PlaceholderJsonSchemaImpl")]
+    #[schema(value_type = String)]
     pub signature: identity::Signature,
 }
 
@@ -492,6 +505,7 @@ pub struct IssuedTicketbooksChallengeResponse {
     pub body: IssuedTicketbooksChallengeResponseBody,
 
     #[schemars(with = "PlaceholderJsonSchemaImpl")]
+    #[schema(value_type = String)]
     pub signature: identity::Signature,
 }
 

nym-api/nym-api-requests/src/models.rs

@@ -41,7 +41,7 @@ use thiserror::Error;
 use time::{Date, OffsetDateTime};
 use utoipa::{IntoParams, ToResponse, ToSchema};
 
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, JsonSchema)]
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, JsonSchema, ToSchema, ToResponse)]
 pub struct RequestError {
     message: String,
 }

nym-api/src/node_status_api/models.rs

@@ -18,6 +18,7 @@ use reqwest::StatusCode;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use sqlx::Error;
+use utoipa::{ToResponse, ToSchema};
 use std::fmt::Display;
 use thiserror::Error;
 use time::{Date, OffsetDateTime};
@@ -315,8 +316,12 @@ impl From<HistoricalUptime> for OldHistoricalUptimeResponse {
 
 // TODO rocket remove smurf name after eliminating `rocket`
 pub(crate) type AxumResult<T> = Result<T, AxumErrorResponse>;
+
+#[derive(ToSchema, ToResponse)]
+#[schema(title = "ErrorResponse")]
 pub(crate) struct AxumErrorResponse {
     message: RequestError,
+    #[schema(value_type = u16)]
     status: StatusCode,
 }
 

nym-api/src/support/http/openapi.rs

@@ -2,9 +2,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 
 #![allow(deprecated)]
-
 use crate::network::handlers::ContractVersionSchemaResponse;
-use nym_api_requests::models;
 use utoipa::OpenApi;
 use utoipauto::utoipauto;
 
@@ -13,7 +11,16 @@ use utoipauto::utoipauto;
 // for automatic model discovery based on ToSchema / IntoParams implementation.
 // Then you can remove `components(schemas)` manual imports below
 
-#[utoipauto(paths = "./nym-api/src")]
+// dependencies which have derive(ToSchema) behind a feature flag with cfg_attr
+// cannot be autodiscovered because proc macros run before feature flags.
+// Tracking issue: https://github.com/ProbablyClem/utoipauto/issues/13
+
+#[utoipauto(paths = "./nym-api/src,
+    ./nym-api/nym-api-requests/src from nym-api-requests,
+    ./common/nym_offline_compact_ecash/src from nym-compact-ecash,
+    ./common/config/src from nym-config,
+    ./common/ticketbooks-merkle/src from nym-ticketbooks-merkle,
+    ./common/nym_offline_compact_ecash/src from nym_compact_ecash")]
 #[derive(OpenApi)]
 #[openapi(
     info(title = "Nym API"),
@@ -24,79 +31,15 @@ use utoipauto::utoipauto;
     ),
     tags(),
     components(schemas(
-        models::CirculatingSupplyResponse,
-        models::CoinSchema,
         nym_mixnet_contract_common::Interval,
-        nym_api_requests::models::NodeRefreshBody,
-        nym_api_requests::models::GatewayStatusReportResponse,
-        nym_api_requests::models::GatewayUptimeHistoryResponse,
-        nym_api_requests::models::GatewayCoreStatusResponse,
-        nym_api_requests::models::GatewayUptimeResponse,
-        nym_api_requests::models::RewardEstimationResponse,
-        nym_api_requests::models::UptimeResponse,
-        nym_api_requests::models::ComputeRewardEstParam,
-        nym_api_requests::models::MixNodeBondAnnotated,
-        nym_api_requests::models::GatewayBondAnnotated,
-        nym_api_requests::models::MixnodeTestResultResponse,
-        nym_api_requests::models::StakeSaturationResponse,
-        nym_api_requests::models::InclusionProbabilityResponse,
-        nym_api_requests::models::AllInclusionProbabilitiesResponse,
-        nym_api_requests::models::InclusionProbability,
-        nym_api_requests::models::SelectionChance,
-        crate::network::models::NetworkDetails,
         nym_config::defaults::NymNetworkDetails,
         nym_config::defaults::ChainDetails,
         nym_config::defaults::DenomDetailsOwned,
         nym_config::defaults::ValidatorDetails,
         nym_config::defaults::NymContracts,
         ContractVersionSchemaResponse,
-        crate::network::models::ContractInformation<ContractVersionSchemaResponse>,
-        nym_api_requests::models::ApiHealthResponse,
-        nym_api_requests::models::ApiStatus,
         nym_bin_common::build_information::BinaryBuildInformationOwned,
-        nym_api_requests::models::SignerInformationResponse,
-        nym_api_requests::models::LegacyDescribedGateway,
-        nym_mixnet_contract_common::Gateway,
-        nym_mixnet_contract_common::GatewayBond,
-        nym_api_requests::models::NymNodeDescription,
-        nym_api_requests::models::HostInformation,
-        nym_api_requests::models::HostKeys,
         nym_node_requests::api::v1::node::models::AuxiliaryDetails,
-        nym_api_requests::models::NetworkRequesterDetails,
-        nym_api_requests::models::IpPacketRouterDetails,
-        nym_api_requests::models::AuthenticatorDetails,
-        nym_api_requests::models::WebSockets,
-        nym_api_requests::nym_nodes::NodeRole,
-        nym_api_requests::models::LegacyDescribedMixNode,
-        nym_api_requests::ecash::VerificationKeyResponse,
-        nym_api_requests::ecash::models::AggregatedExpirationDateSignatureResponse,
-        nym_api_requests::ecash::models::AggregatedCoinIndicesSignatureResponse,
-        nym_api_requests::ecash::models::MasterVerificationKeyResponse,
-        nym_api_requests::ecash::models::BlindedSignatureResponse,
-        nym_api_requests::ecash::models::BlindSignRequestBody,
-        nym_api_requests::ecash::models::PartialExpirationDateSignatureResponse,
-        nym_api_requests::ecash::models::PartialCoinIndicesSignatureResponse,
-        nym_api_requests::ecash::models::EcashTicketVerificationResponse,
-        nym_api_requests::ecash::models::EcashTicketVerificationRejection,
-        nym_api_requests::ecash::models::EcashBatchTicketRedemptionResponse,
-        nym_api_requests::ecash::models::VerifyEcashTicketBody,
-        nym_api_requests::ecash::models::VerifyEcashCredentialBody,
-        nym_api_requests::ecash::models::CommitedDeposit,
-        nym_api_requests::ecash::models::IssuedTicketbooksForResponseBody,
-        nym_api_requests::ecash::models::IssuedTicketbooksForResponse,
-        nym_api_requests::ecash::models::IssuedTicketbooksChallengeRequest,
-        nym_api_requests::ecash::models::IssuedTicketbooksChallengeResponseBody,
-        nym_api_requests::ecash::models::IssuedTicketbooksChallengeResponse,
-        nym_api_requests::nym_nodes::SkimmedNode,
-        nym_api_requests::nym_nodes::SemiSkimmedNode,
-        nym_api_requests::nym_nodes::FullFatNode,
-        nym_api_requests::nym_nodes::BasicEntryInformation,
-        nym_api_requests::nym_nodes::NodeRoleQueryParam,
-        nym_api_requests::models::AnnotationResponse,
-        nym_api_requests::models::NodePerformanceResponse,
-        nym_api_requests::models::NodeDatePerformanceResponse,
-        nym_api_requests::models::PerformanceHistoryResponse,
-        nym_api_requests::models::UptimeHistoryResponse,
     ))
 )]
 pub(crate) struct ApiDoc;

nym-credential-proxy/nym-credential-proxy/src/http/types.rs

@@ -13,7 +13,6 @@ use uuid::Uuid;
 #[response(description = "Error response with additional message")]
 pub struct RequestError {
     pub inner: ErrorResponse,
-
     pub status: StatusCode,
 }
 

nym-node-status-api/nym-node-status-api/src/http/api_docs.rs

@@ -1,4 +1,3 @@
-use crate::http::{Gateway, GatewaySkinny, Mixnode, Service, SessionStats};
 use utoipa::OpenApi;
 use utoipauto::utoipauto;