manta_server/server/
api_doc.rs

1//! OpenAPI specification document for the manta HTTP server.
2//!
3//! [`ApiDoc`] is consumed by [`super::routes::build_router`] and
4//! served at `GET /openapi.json`, with Swagger UI mounted at
5//! `GET /docs`. Every handler in [`super::handlers`] that should
6//! appear in the spec must be listed under the `paths(...)` attribute
7//! below, and every wire-type used in request/response bodies must
8//! be listed under `components(schemas(...))`. The `SecurityAddon`
9//! `Modify` impl registers the `bearerAuth` (HTTP `Bearer` / JWT)
10//! security scheme and declares `/api/v1` as the spec's server URL
11//! so Swagger UI's "Try it out" buttons build full paths.
12
13use utoipa::{
14  Modify, OpenApi,
15  openapi::security::{HttpAuthScheme, HttpBuilder, SecurityScheme},
16};
17
18use super::handlers;
19
20/// Root OpenAPI document for the manta API.
21#[derive(OpenApi)]
22#[openapi(
23  paths(
24    handlers::health,
25    handlers::get_sessions,
26    handlers::get_image_analysis,
27    handlers::get_configurations,
28    handlers::get_nodes,
29    handlers::get_groups,
30    handlers::get_images,
31    handlers::get_templates,
32    handlers::get_boot_parameters,
33    handlers::get_kernel_parameters,
34    handlers::get_redfish_endpoints,
35    handlers::get_groups_nodes,
36    handlers::get_groups_hardware,
37    handlers::get_clusters_deprecated,
38    handlers::get_hardware_clusters_deprecated,
39    handlers::get_hardware_nodes_list,
40    handlers::delete_node,
41    handlers::add_node,
42    handlers::delete_group,
43    handlers::create_group,
44    handlers::add_nodes_to_group,
45    handlers::delete_group_members,
46    handlers::delete_boot_parameters,
47    handlers::add_boot_parameters,
48    handlers::update_boot_parameters,
49    handlers::delete_redfish_endpoint,
50    handlers::add_redfish_endpoint,
51    handlers::update_redfish_endpoint,
52    handlers::delete_session,
53    handlers::delete_images,
54    handlers::delete_configurations,
55    handlers::create_session,
56    handlers::apply_boot_config,
57    handlers::apply_kernel_parameters,
58    handlers::add_kernel_parameters,
59    handlers::delete_kernel_parameters,
60    handlers::migrate_nodes,
61    handlers::migrate_backup,
62    handlers::migrate_restore,
63    handlers::create_ephemeral_env,
64    handlers::post_power,
65    handlers::get_power_transition,
66    handlers::post_template_session,
67    handlers::get_session_logs,
68    handlers::post_sat_configuration,
69    handlers::post_sat_image_cfs_session,
70    handlers::post_sat_image_stamp,
71    handlers::post_sat_session_template,
72    handlers::post_sat_validate,
73    handlers::add_hw_component,
74    handlers::delete_hw_component,
75    handlers::apply_hw_configuration,
76    handlers::console_node_ws,
77    handlers::console_session_ws,
78    handlers::auth_token,
79    handlers::auth_validate,
80    handlers::get_available_groups,
81  ),
82  components(schemas(
83    handlers::ErrorResponse,
84    handlers::AddNodeRequest,
85    handlers::AddNodesToGroupRequest,
86    handlers::AddNodesToGroupResponse,
87    handlers::DeleteBootParametersRequest,
88    handlers::CreateSessionRequest,
89    handlers::ApplyBootConfigRequest,
90    handlers::KernelParamOp,
91    handlers::ApplyKernelParametersRequest,
92    handlers::MigrateNodesRequest,
93    handlers::MigrateBackupRequest,
94    handlers::MigrateRestoreRequest,
95    handlers::CreateEphemeralEnvRequest,
96    handlers::DeleteGroupMembersRequest,
97    handlers::PowerAction,
98    handlers::PowerTargetType,
99    handlers::PowerRequest,
100    handlers::BosOperation,
101    handlers::PostTemplateSessionRequest,
102    handlers::AddKernelParametersRequest,
103    handlers::DeleteKernelParametersRequest,
104    handlers::AddHwComponentRequest,
105    handlers::DeleteHwComponentRequest,
106    handlers::HwClusterMode,
107    handlers::ApplyHwConfigurationRequest,
108    manta_shared::types::auth::AuthTokenRequest,
109    manta_shared::types::auth::AuthTokenResponse,
110    manta_shared::types::auth::ValidateTokenRequest,
111    crate::service::boot_parameters::UpdateBootParametersParams,
112    manta_shared::types::api::redfish_endpoints::UpdateRedfishEndpointParams,
113    manta_shared::types::dto::NodeDetails,
114    manta_shared::types::api::responses::CreatedResponse,
115    manta_shared::types::api::responses::AddNodeResponse,
116    manta_shared::types::api::responses::CreateSessionResponse,
117    manta_shared::types::api::responses::EphemeralEnvResponse,
118    manta_shared::types::api::responses::CompletedResponse,
119    manta_shared::types::api::responses::MigrateNodesPairResult,
120    manta_shared::types::api::responses::MigrateNodesResponse,
121    manta_shared::types::api::analysis::BackendSummary,
122    manta_shared::types::api::configuration_analysis::ConfigurationAnalysis,
123    manta_backend_dispatcher::types::Group,
124    manta_backend_dispatcher::types::Member,
125    manta_backend_dispatcher::types::bss::BootParameters,
126  )),
127  modifiers(&SecurityAddon),
128  info(
129    title = "Manta API",
130    version = env!("CARGO_PKG_VERSION"),
131    description = "REST API for managing CSM/OpenCHAMI HPC clusters via manta.",
132  )
133)]
134pub struct ApiDoc;
135
136struct SecurityAddon;
137
138impl Modify for SecurityAddon {
139  fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
140    if let Some(components) = openapi.components.as_mut() {
141      components.add_security_scheme(
142        "bearerAuth",
143        SecurityScheme::Http(
144          HttpBuilder::new()
145            .scheme(HttpAuthScheme::Bearer)
146            .bearer_format("JWT")
147            .build(),
148        ),
149      );
150    }
151    // Declare the /api/v1 base path as the server so that Swagger UI
152    // constructs full URLs like /api/v1/sessions when trying out calls.
153    openapi.servers = Some(vec![
154      utoipa::openapi::ServerBuilder::new()
155        .url("/api/v1")
156        .description(Some("manta API v1"))
157        .build(),
158    ]);
159  }
160}
manta_server/server/api_doc.rs

manta_server/server/
api_doc.rs
