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 `/v2` 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_runtime_configuration,
58    handlers::apply_kernel_parameters,
59    handlers::add_kernel_parameters,
60    handlers::delete_kernel_parameters,
61    handlers::migrate_nodes,
62    handlers::migrate_backup,
63    handlers::migrate_restore,
64    handlers::create_ephemeral_env,
65    handlers::post_power,
66    handlers::get_power_transition,
67    handlers::post_template_session,
68    handlers::get_session_logs,
69    handlers::post_sat_configuration,
70    handlers::post_sat_image_cfs_session,
71    handlers::post_sat_image_stamp,
72    handlers::post_sat_session_template,
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::ApplyRuntimeConfigurationRequest,
91    handlers::KernelParamOp,
92    handlers::ApplyKernelParametersRequest,
93    handlers::MigrateNodesRequest,
94    handlers::MigrateBackupRequest,
95    handlers::MigrateRestoreRequest,
96    handlers::CreateEphemeralEnvRequest,
97    handlers::DeleteGroupMembersRequest,
98    handlers::PowerAction,
99    handlers::PowerTargetType,
100    handlers::PowerRequest,
101    handlers::BosOperation,
102    handlers::PostTemplateSessionRequest,
103    handlers::AddKernelParametersRequest,
104    handlers::DeleteKernelParametersRequest,
105    handlers::AddHwComponentRequest,
106    handlers::DeleteHwComponentRequest,
107    handlers::HwClusterMode,
108    handlers::ApplyHwConfigurationRequest,
109    manta_shared::types::auth::AuthTokenRequest,
110    manta_shared::types::auth::AuthTokenResponse,
111    manta_shared::types::auth::ValidateTokenRequest,
112    crate::service::boot_parameters::UpdateBootParametersParams,
113    manta_shared::types::api::redfish_endpoints::UpdateRedfishEndpointParams,
114    manta_shared::types::dto::NodeDetails,
115    manta_shared::types::api::responses::CreatedResponse,
116    manta_shared::types::api::responses::AddNodeResponse,
117    manta_shared::types::api::responses::CreateSessionResponse,
118    manta_shared::types::api::responses::EphemeralEnvResponse,
119    manta_shared::types::api::responses::CompletedResponse,
120    manta_shared::types::api::responses::MigrateNodesPairResult,
121    manta_shared::types::api::responses::MigrateNodesResponse,
122    manta_shared::types::api::analysis::BackendSummary,
123    manta_shared::types::api::configuration_analysis::ConfigurationAnalysis,
124    manta_backend_dispatcher::types::Group,
125    manta_backend_dispatcher::types::Member,
126    manta_backend_dispatcher::types::bss::BootParameters,
127  )),
128  modifiers(&SecurityAddon),
129  info(
130    title = "Manta API",
131    version = env!("CARGO_PKG_VERSION"),
132    description = "REST API for managing CSM/OpenCHAMI HPC clusters via manta.",
133  )
134)]
135pub struct ApiDoc;
136
137struct SecurityAddon;
138
139impl Modify for SecurityAddon {
140  fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
141    if let Some(components) = openapi.components.as_mut() {
142      components.add_security_scheme(
143        "bearerAuth",
144        SecurityScheme::Http(
145          HttpBuilder::new()
146            .scheme(HttpAuthScheme::Bearer)
147            .bearer_format("JWT")
148            .build(),
149        ),
150      );
151    }
152    // Declare the /v2 base path as the server so that Swagger UI
153    // constructs full URLs like /v2/sessions when trying out calls.
154    openapi.servers = Some(vec![
155      utoipa::openapi::ServerBuilder::new()
156        .url("/v2")
157        .description(Some("manta API v2"))
158        .build(),
159    ]);
160  }
161}
manta_server/server/api_doc.rs

manta_server/server/
api_doc.rs
