Extend swagger docs (#5235)

* WIP adding derive(ToSchema)

* Derive ToSchema for more types

* ContractBuildInformation on /nym_contracts_detailed

* rustfmt

* Add cfg_attr

* A bunch of annotations

* Compiles with utoipa 5.2

* WIP

* Post rebase fixes

* Gitattributes to ignore .sqlx diffs

* generate Sqlx schema files

* Improvements

* Move ecash schema out of ecash crate

* Move redocly config to nym-api/

* Move redocly config to nym-api/

* Remove ErrorResponse

* Move generated openapi spec to .gitignore

* Include BSL licence

* Remove utoipa from ecash toml file

* Remove placeholder annotations

* Chain-watcher rebase changes

* Update licence info

* Treat Scalar as String in OpenAPI

nym-node/src/node/http/router/api/v1/authenticator/root.rs

@@ -15,8 +15,8 @@ use nym_node_requests::api::v1::authenticator::models::Authenticator;
     responses(
         (status = 501, description = "the endpoint hasn't been implemented yet"),
         (status = 200, content(
-            ("application/json" = Authenticator),
-            ("application/yaml" = Authenticator)
+            (Authenticator = "application/json"),
+            (Authenticator = "application/yaml")
         ))
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/gateway/client_interfaces/mod.rs

@@ -45,8 +45,8 @@ pub(crate) fn routes<S: Send + Sync + 'static + Clone>(
     responses(
     (status = 501, description = "the endpoint hasn't been implemented yet"),
         (status = 200, content(
-            ("application/json" = ClientInterfaces),
-            ("application/yaml" = ClientInterfaces)
+            (ClientInterfaces = "application/json"),
+            (ClientInterfaces = "application/yaml")
         ))
     ),
     params(OutputParams)
@@ -71,8 +71,8 @@ pub type ClientInterfacesResponse = FormattedResponse<ClientInterfaces>;
     responses(
         (status = 501, description = "the endpoint hasn't been implemented yet"),
         (status = 200, content(
-            ("application/json" = WebSockets),
-            ("application/yaml" = WebSockets)
+            (WebSockets = "application/json"),
+            (WebSockets = "application/yaml")
         ))
     ),
     params(OutputParams)
@@ -97,8 +97,8 @@ pub type MixnetWebSocketsResponse = FormattedResponse<WebSockets>;
     responses(
         (status = 501, description = "the endpoint hasn't been implemented yet"),
         (status = 200, content(
-            ("application/json" = Wireguard),
-            ("application/yaml" = Wireguard)
+            (Wireguard = "application/json"),
+            (Wireguard = "application/yaml")
         ))
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/gateway/root.rs

@@ -15,8 +15,8 @@ use nym_node_requests::api::v1::gateway::models::Gateway;
     responses(
         (status = 501, description = "the endpoint hasn't been implemented yet"),
         (status = 200, content(
-            ("application/json" = Gateway),
-            ("application/yaml" = Gateway)
+            (Gateway = "application/json"),
+            (Gateway = "application/yaml")
         ))
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/health.rs

@@ -14,8 +14,8 @@ use nym_node_requests::api::v1::health::models::NodeHealth;
     tag = "Health",
     responses(
         (status = 200, content(
-            ("application/json" = Vec<NodeHealth>),
-            ("application/yaml" = Vec<NodeHealth>)
+            (Vec<NodeHealth> = "application/json"),
+            (Vec<NodeHealth> = "application/yaml")
         ),  description = "the api is available and healthy")
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/ip_packet_router/root.rs

@@ -15,8 +15,8 @@ use nym_node_requests::api::v1::ip_packet_router::models::IpPacketRouter;
     responses(
         (status = 501, description = "the endpoint hasn't been implemented yet"),
         (status = 200, content(
-            ("application/json" = IpPacketRouter),
-            ("application/yaml" = IpPacketRouter)
+            (IpPacketRouter = "application/json"),
+            (IpPacketRouter = "application/yaml")
         ))
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/metrics/legacy_mixing.rs

@@ -16,8 +16,8 @@ use nym_node_requests::api::v1::metrics::models::LegacyMixingStats;
     tag = "Metrics",
     responses(
         (status = 200, content(
-            ("application/json" = LegacyMixingStats),
-            ("application/yaml" = LegacyMixingStats)
+            (LegacyMixingStats = "application/json"),
+            (LegacyMixingStats = "application/yaml")
         ))
     ),
     params(OutputParams),

nym-node/src/node/http/router/api/v1/metrics/packets_stats.rs

@@ -18,8 +18,8 @@ use nym_node_requests::api::v1::metrics::models::packets::{
     tag = "Metrics",
     responses(
         (status = 200, content(
-            ("application/json" = PacketsStats),
-            ("application/yaml" = PacketsStats)
+            (PacketsStats = "application/json"),
+            (PacketsStats = "application/yaml")
         ))
     ),
     params(OutputParams),

nym-node/src/node/http/router/api/v1/metrics/sessions.rs

@@ -17,8 +17,8 @@ use time::macros::time;
     tag = "Metrics",
     responses(
         (status = 200, content(
-            ("application/json" = SessionStats),
-            ("application/yaml" = SessionStats)
+            (SessionStats = "application/json"),
+            (SessionStats = "application/yaml")
         ))
     ),
     params(OutputParams),

nym-node/src/node/http/router/api/v1/metrics/verloc.rs

@@ -1,14 +1,15 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: GPL-3.0-only
 
-use crate::node::http::state::metrics::MetricsAppState;
 use axum::extract::{Query, State};
 use nym_http_api_common::{FormattedResponse, OutputParams};
 use nym_node_requests::api::v1::metrics::models::{
-    VerlocMeasurement, VerlocNodeResult, VerlocResult, VerlocResultData, VerlocStats,
+    VerlocNodeResult, VerlocResult, VerlocResultData, VerlocStats,
 };
 use nym_verloc::measurements::SharedVerlocStats;
 
+use crate::node::http::state::metrics::MetricsAppState;
+
 /// If applicable, returns verloc statistics information of this node.
 #[utoipa::path(
     get,
@@ -17,8 +18,8 @@ use nym_verloc::measurements::SharedVerlocStats;
     tag = "Metrics",
     responses(
         (status = 200, content(
-            ("application/json" = VerlocStats),
-            ("application/yaml" = VerlocStats)
+            (VerlocStats = "application/json"),
+            (VerlocStats = "application/yaml")
         ))
     ),
     params(OutputParams),
@@ -42,12 +43,6 @@ async fn build_response(verloc_stats: &SharedVerlocStats) -> VerlocStats {
                 .iter()
                 .map(|r| VerlocNodeResult {
                     node_identity: r.node_identity,
-                    latest_measurement: r.latest_measurement.map(|l| VerlocMeasurement {
-                        minimum: l.minimum,
-                        mean: l.mean,
-                        maximum: l.maximum,
-                        standard_deviation: l.standard_deviation,
-                    }),
                 })
                 .collect(),
         }

nym-node/src/node/http/router/api/v1/metrics/wireguard.rs

@@ -16,8 +16,8 @@ use nym_node_requests::api::v1::metrics::models::WireguardStats;
     tag = "Metrics",
     responses(
         (status = 200, content(
-            ("application/json" = WireguardStats),
-            ("application/yaml" = WireguardStats)
+            (WireguardStats = "application/json"),
+            (WireguardStats = "application/yaml")
         ))
     ),
     params(OutputParams),

nym-node/src/node/http/router/api/v1/mixnode/root.rs

@@ -15,8 +15,8 @@ use nym_node_requests::api::v1::mixnode::models::Mixnode;
     responses(
         (status = 501, description = "the endpoint hasn't been implemented yet"),
         (status = 200, content(
-            ("application/json" = Mixnode),
-            ("application/yaml" = Mixnode)
+            (Mixnode = "application/json"),
+            (Mixnode = "application/yaml")
         ))
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/network_requester/exit_policy.rs

@@ -13,8 +13,8 @@ use nym_node_requests::api::v1::network_requester::exit_policy::models::UsedExit
     tag = "Network Requester",
     responses(
         (status = 200, content(
-            ("application/json" = UsedExitPolicy),
-            ("application/yaml" = UsedExitPolicy)
+            (UsedExitPolicy = "application/json"),
+            (UsedExitPolicy = "application/yaml")
         ))
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/network_requester/root.rs

@@ -15,8 +15,8 @@ use nym_node_requests::api::v1::network_requester::models::NetworkRequester;
     responses(
         (status = 501, description = "the endpoint hasn't been implemented yet"),
         (status = 200, content(
-            ("application/json" = NetworkRequester),
-            ("application/yaml" = NetworkRequester)
+            (NetworkRequester = "application/json"),
+            (NetworkRequester = "application/yaml")
         ))
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/node/auxiliary.rs

@@ -14,8 +14,8 @@ use nym_node_requests::api::v1::node::models::AuxiliaryDetails;
     tag = "Node",
     responses(
         (status = 200, content(
-            ("application/json" = AuxiliaryDetails),
-            ("application/yaml" = AuxiliaryDetails)
+            (AuxiliaryDetails = "application/json"),
+            (AuxiliaryDetails = "application/yaml")
         )),
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/node/build_information.rs

@@ -13,8 +13,8 @@ use nym_node_requests::api::v1::node::models::BinaryBuildInformationOwned;
     tag = "Node",
     responses(
         (status = 200, content(
-            ("application/json" = BinaryBuildInformationOwned),
-            ("application/yaml" = BinaryBuildInformationOwned)
+            (BinaryBuildInformationOwned = "application/json"),
+            (BinaryBuildInformationOwned = "application/yaml")
         ))
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/node/description.rs

@@ -14,8 +14,8 @@ use nym_node_requests::api::v1::node::models::NodeDescription;
     tag = "Node",
     responses(
         (status = 200, content(
-            ("application/json" = NodeDescription),
-            ("application/yaml" = NodeDescription)
+            (NodeDescription = "application/json"),
+            (NodeDescription = "application/yaml")
         )),
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/node/hardware.rs

@@ -15,10 +15,10 @@ use nym_node_requests::api::v1::node::models::HostSystem;
     tag = "Node",
     responses(
         (status = 200, content(
-            ("application/json" = HostSystem),
-            ("application/yaml" = HostSystem)
+            (HostSystem = "application/json"),
+            (HostSystem = "application/yaml")
         )),
-        (status = 403, body = ErrorResponse, description = "the node does not wish to expose the system information")
+        (status = 403, body = String, description = "the node does not wish to expose the system information")
     ),
     params(OutputParams)
 )]

nym-node/src/node/http/router/api/v1/node/host_information.rs

@@ -3,7 +3,7 @@
 
 use axum::extract::Query;
 use nym_http_api_common::{FormattedResponse, OutputParams};
-use nym_node_requests::api::v1::node::models::SignedHostInformation;
+use nym_node_requests::api::{v1::node::models::SignedHostInformation, SignedDataHostInfo};
 
 /// Returns host information of this node.
 #[utoipa::path(
@@ -13,8 +13,8 @@ use nym_node_requests::api::v1::node::models::SignedHostInformation;
     tag = "Node",
     responses(
         (status = 200, content(
-            ("application/json" = SignedHostInformation),
-            ("application/yaml" = SignedHostInformation)
+            (SignedDataHostInfo = "application/json"),
+            (SignedDataHostInfo = "application/yaml")
         ))
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/node/roles.rs

@@ -13,8 +13,8 @@ use nym_node_requests::api::v1::node::models::NodeRoles;
     tag = "Node",
     responses(
         (status = 200, content(
-            ("application/json" = NodeRoles),
-            ("application/yaml" = NodeRoles)
+            (NodeRoles = "application/json"),
+            (NodeRoles = "application/yaml")
         ))
     ),
     params(OutputParams)

nym-node/src/node/http/router/api/v1/openapi.rs

@@ -2,7 +2,6 @@
 // SPDX-License-Identifier: GPL-3.0-only
 
 use crate::node::http::router::api;
-use crate::node::http::router::types::{ErrorResponse, RequestError};
 use axum::Router;
 use nym_node_requests::api as api_requests;
 use nym_node_requests::routes::api::{v1, v1_absolute};
@@ -35,13 +34,11 @@ use utoipa_swagger_ui::SwaggerUi;
     ),
     components(
         schemas(
-            ErrorResponse,
             nym_http_api_common::Output,
             nym_http_api_common::OutputParams,
             api_requests::v1::health::models::NodeHealth,
             api_requests::v1::health::models::NodeStatus,
             api_requests::v1::node::models::BinaryBuildInformationOwned,
-            api_requests::v1::node::models::SignedHostInformation,
             api_requests::v1::node::models::HostInformation,
             api_requests::v1::node::models::HostKeys,
             api_requests::v1::node::models::NodeRoles,
@@ -71,7 +68,6 @@ use utoipa_swagger_ui::SwaggerUi;
             api_requests::v1::network_requester::exit_policy::models::UsedExitPolicy,
             api_requests::v1::ip_packet_router::models::IpPacketRouter,
         ),
-        responses(RequestError),
     ),
     modifiers(&SecurityAddon),
 )]

nym-node/src/node/http/router/types.rs

@@ -5,10 +5,8 @@ use axum::http::StatusCode;
 use axum::response::{IntoResponse, Response};
 use axum::Json;
 pub use nym_node_requests::api::ErrorResponse;
-use utoipa::ToResponse;
 
-#[derive(Debug, Clone, ToResponse)]
-#[response(description = "Error response with additional message")]
+#[derive(Debug, Clone)]
 pub(crate) struct RequestError {
     pub(crate) inner: ErrorResponse,