Many fixes to the OpenAPI documentation

rust/agama-lib/src/network/settings.rs

@@ -74,7 +74,7 @@ pub struct NetworkDevice {
  pub state: DeviceState,
 }
 
-#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+#[derive(Clone, Debug, Default, Serialize, Deserialize, utoipa::ToSchema)]
 pub struct NetworkConnection {
  pub id: String,
  #[serde(skip_serializing_if = "Option::is_none")]

rust/agama-server/src/l10n/web.rs

@@ -76,18 +76,28 @@ pub struct LocaleConfig {
  ui_keymap: Option<String>,
 }
 
-#[utoipa::path(get, path = "/l10n/timezones", responses(
- (status = 200, description = "List of known timezones")
-))]
+#[utoipa::path(
+ get,
+ path = "/timezones",
+ context_path = "/api/l10n",
+ responses(
+ (status = 200, description = "List of known timezones", body = Vec<TimezoneEntry>)
+ )
+)]
 async fn timezones(State(state): State<LocaleState<'_>>) -> Json<Vec<TimezoneEntry>> {
  let data = state.locale.read().await;
  let timezones = data.timezones_db.entries().to_vec();
  Json(timezones)
 }
 
-#[utoipa::path(get, path = "/l10n/keymaps", responses(
- (status = 200, description = "List of known keymaps", body = Vec<Keymap>)
-))]
+#[utoipa::path(
+ get,
+ path = "/keymaps",
+ context_path = "/api/l10n",
+ responses(
+ (status = 200, description = "List of known keymaps", body = Vec<Keymap>)
+ )
+)]
 async fn keymaps(State(state): State<LocaleState<'_>>) -> Json<Vec<Keymap>> {
  let data = state.locale.read().await;
  let keymaps = data.keymaps_db.entries().to_vec();
@@ -96,9 +106,15 @@ async fn keymaps(State(state): State<LocaleState<'_>>) -> Json<Vec<Keymap>> {
 
 // TODO: update all or nothing
 // TODO: send only the attributes that have changed
-#[utoipa::path(patch, path = "/l10n/config", responses(
- (status = 204, description = "Set the locale configuration", body = LocaleConfig)
-))]
+#[utoipa::path(
+ patch,
+ path = "/config",
+ context_path = "/api/l10n",
+ operation_id = "set_l10n_config",
+ responses(
+ (status = 204, description = "Set the locale configuration", body = LocaleConfig)
+ )
+)]
 async fn set_config(
  State(state): State<LocaleState<'_>>,
  Json(value): Json<LocaleConfig>,
@@ -148,9 +164,15 @@ async fn set_config(
  Ok(StatusCode::NO_CONTENT)
 }
 
-#[utoipa::path(get, path = "/l10n/config", responses(
- (status = 200, description = "Localization configuration", body = LocaleConfig)
-))]
+#[utoipa::path(
+ get,
+ path = "/config",
+ context_path = "/api/l10n",
+ operation_id = "get_l10n_config",
+ responses(
+ (status = 200, description = "Localization configuration", body = LocaleConfig)
+ )
+)]
 async fn get_config(State(state): State<LocaleState<'_>>) -> Json<LocaleConfig> {
  let data = state.locale.read().await;
  Json(LocaleConfig {

rust/agama-server/src/manager/web.rs

@@ -96,36 +96,56 @@ pub async fn manager_service(dbus: zbus::Connection) -> Result<Router, ServiceEr
 }
 
 /// Starts the probing process.
-#[utoipa::path(get, path = "/api/manager/probe", responses(
- (status = 200, description = "The probing process was started.")
-))]
+#[utoipa::path(
+ get,
+ path = "/probe",
+ context_path = "/api/manager",
+ responses(
+ (status = 200, description = "The probing process was started.")
+ )
+)]
 async fn probe_action(State(state): State<ManagerState<'_>>) -> Result<(), Error> {
  state.manager.probe().await?;
  Ok(())
 }
 
 /// Starts the probing process.
-#[utoipa::path(get, path = "/api/manager/install", responses(
- (status = 200, description = "The installation process was started.")
-))]
+#[utoipa::path(
+ get,
+ path = "/install",
+ context_path = "/api/manager",
+ responses(
+ (status = 200, description = "The installation process was started.")
+ )
+)]
 async fn install_action(State(state): State<ManagerState<'_>>) -> Result<(), Error> {
  state.manager.install().await?;
  Ok(())
 }
 
 /// Executes the post installation tasks (e.g., rebooting the system).
-#[utoipa::path(get, path = "/api/manager/install", responses(
- (status = 200, description = "The installation tasks are executed.")
-))]
+#[utoipa::path(
+ get,
+ path = "/install",
+ context_path = "/api/manager",
+ responses(
+ (status = 200, description = "The installation tasks are executed.")
+ )
+)]
 async fn finish_action(State(state): State<ManagerState<'_>>) -> Result<(), Error> {
  state.manager.finish().await?;
  Ok(())
 }
 
 /// Returns the manager status.
-#[utoipa::path(get, path = "/api/manager/installer", responses(
- (status = 200, description = "Installation status.", body = ManagerStatus)
-))]
+#[utoipa::path(
+ get,
+ path = "/installer",
+ context_path = "/api/manager",
+ responses(
+ (status = 200, description = "Installation status.", body = InstallerStatus)
+ )
+)]
 async fn installer_status(
  State(state): State<ManagerState<'_>>,
 ) -> Result<Json<InstallerStatus>, Error> {

rust/agama-server/src/network/model.rs

@@ -38,7 +38,7 @@ impl Default for StateConfig {
  }
 }
 
-#[derive(Default, Clone, Debug, utoipa::ToSchema)]
+#[derive(Default, Clone, Debug)]
 pub struct NetworkState {
  pub general_state: GeneralState,
  pub access_points: Vec<AccessPoint>,

rust/agama-server/src/network/web.rs

@@ -110,19 +110,29 @@ pub async fn network_service<T: Adapter + Send + Sync + 'static>(
  .with_state(state))
 }
 
-#[utoipa::path(get, path = "/network/state", responses(
- (status = 200, description = "Get general network config", body = GenereralState)
-))]
+#[utoipa::path(
+ get,
+ path = "/state",
+ context_path = "/api/network",
+ responses(
+ (status = 200, description = "Get general network config", body = GenereralState)
+ )
+)]
 async fn general_state(
  State(state): State<NetworkServiceState>,
 ) -> Result<Json<GeneralState>, NetworkError> {
  let general_state = state.network.get_state().await?;
  Ok(Json(general_state))
 }
 
-#[utoipa::path(put, path = "/network/state", responses(
- (status = 200, description = "Update general network config", body = GenereralState)
-))]
+#[utoipa::path(
+ put,
+ path = "/state",
+ context_path = "/api/network",
+ responses(
+ (status = 200, description = "Update general network config", body = GenereralState)
+ )
+)]
 async fn update_general_state(
  State(state): State<NetworkServiceState>,
  Json(value): Json<GeneralState>,
@@ -132,9 +142,14 @@ async fn update_general_state(
  Ok(Json(state))
 }
 
-#[utoipa::path(get, path = "/network/wifi", responses(
- (status = 200, description = "List of wireless networks", body = Vec<AccessPoint>)
-))]
+#[utoipa::path(
+ get,
+ path = "/wifi",
+ context_path = "/api/network",
+ responses(
+ (status = 200, description = "List of wireless networks", body = Vec<AccessPoint>)
+ )
+)]
 async fn wifi_networks(
  State(state): State<NetworkServiceState>,
 ) -> Result<Json<Vec<AccessPoint>>, NetworkError> {
@@ -151,36 +166,28 @@ async fn wifi_networks(
  Ok(Json(networks))
 }
 
-#[utoipa::path(get, path = "/network/devices", responses(
- (status = 200, description = "List of devices", body = Vec<Device>)
-))]
+#[utoipa::path(
+ get,
+ path = "/devices",
+ context_path = "/api/network",
+ responses(
+ (status = 200, description = "List of devices", body = Vec<Device>)
+ )
+)]
 async fn devices(
  State(state): State<NetworkServiceState>,
 ) -> Result<Json<Vec<Device>>, NetworkError> {
  Ok(Json(state.network.get_devices().await?))
 }
 
-#[utoipa::path(get, path = "/network/connections/:id", responses(
- (status = 200, description = "Get connection given by its ID", body = NetworkConnection)
-))]
-async fn connection(
- State(state): State<NetworkServiceState>,
- Path(id): Path<String>,
-) -> Result<Json<NetworkConnection>, NetworkError> {
- let conn = state
- .network
- .get_connection(&id)
- .await?
- .ok_or_else(|| NetworkError::UnknownConnection(id.clone()))?;
-
- let conn = NetworkConnection::try_from(conn)?;
-
- Ok(Json(conn))
-}
-
-#[utoipa::path(get, path = "/network/connections", responses(
- (status = 200, description = "List of known connections", body = Vec<NetworkConnection>)
-))]
+#[utoipa::path(
+ get,
+ path = "/connections",
+ context_path = "/api/network",
+ responses(
+ (status = 200, description = "List of known connections", body = Vec<NetworkConnection>)
+ )
+)]
 async fn connections(
  State(state): State<NetworkServiceState>,
 ) -> Result<Json<Vec<NetworkConnection>>, NetworkError> {
@@ -193,9 +200,14 @@ async fn connections(
  Ok(Json(connections))
 }
 
-#[utoipa::path(post, path = "/network/connections", responses(
- (status = 200, description = "Add a new connection", body = Connection)
-))]
+#[utoipa::path(
+ post,
+ path = "/connections",
+ context_path = "/api/network",
+ responses(
+ (status = 200, description = "Add a new connection", body = Connection)
+ )
+)]
 async fn add_connection(
  State(state): State<NetworkServiceState>,
  Json(conn): Json<NetworkConnection>,
@@ -210,9 +222,36 @@ async fn add_connection(
  }
 }
 
-#[utoipa::path(delete, path = "/network/connections/:id", responses(
- (status = 200, description = "Delete connection", body = Connection)
-))]
+#[utoipa::path(
+ get,
+ path = "/network/connections/:id",
+ responses(
+ (status = 200, description = "Get connection given by its ID", body = NetworkConnection)
+ )
+)]
+async fn connection(
+ State(state): State<NetworkServiceState>,
+ Path(id): Path<String>,
+) -> Result<Json<NetworkConnection>, NetworkError> {
+ let conn = state
+ .network
+ .get_connection(&id)
+ .await?
+ .ok_or_else(|| NetworkError::UnknownConnection(id.clone()))?;
+
+ let conn = NetworkConnection::try_from(conn)?;
+
+ Ok(Json(conn))
+}
+
+#[utoipa::path(
+ delete,
+ path = "/connections/:id",
+ context_path = "/api/network",
+ responses(
+ (status = 200, description = "Delete connection", body = Connection)
+ )
+)]
 async fn delete_connection(
  State(state): State<NetworkServiceState>,
  Path(id): Path<String>,
@@ -224,9 +263,14 @@ async fn delete_connection(
  }
 }
 
-#[utoipa::path(put, path = "/network/connections/:id", responses(
- (status = 204, description = "Update connection", body = Connection)
-))]
+#[utoipa::path(
+ put,
+ path = "/connections/:id",
+ context_path = "/api/network",
+ responses(
+ (status = 204, description = "Update connection", body = Connection)
+ )
+)]
 async fn update_connection(
  State(state): State<NetworkServiceState>,
  Path(id): Path<String>,
@@ -249,9 +293,14 @@ async fn update_connection(
  Ok(StatusCode::NO_CONTENT)
 }
 
-#[utoipa::path(get, path = "/network/connections/:id/connect", responses(
- (status = 204, description = "Connect to the given connection", body = String)
-))]
+#[utoipa::path(
+ get,
+ path = "/connections/:id/connect",
+ context_path = "/api/network",
+ responses(
+ (status = 204, description = "Connect to the given connection", body = String)
+ )
+)]
 async fn connect(
  State(state): State<NetworkServiceState>,
  Path(id): Path<String>,
@@ -270,9 +319,14 @@ async fn connect(
  Ok(StatusCode::NO_CONTENT)
 }
 
-#[utoipa::path(get, path = "/network/connections/:id/disconnect", responses(
- (status = 204, description = "Connect to the given connection", body = String)
-))]
+#[utoipa::path(
+ get,
+ path = "/connections/:id/disconnect",
+ context_path = "/api/network",
+ responses(
+ (status = 204, description = "Connect to the given connection", body = String)
+ )
+)]
 async fn disconnect(
  State(state): State<NetworkServiceState>,
  Path(id): Path<String>,
@@ -291,9 +345,14 @@ async fn disconnect(
  Ok(StatusCode::NO_CONTENT)
 }
 
-#[utoipa::path(put, path = "/network/system/apply", responses(
- (status = 204, description = "Apply configuration")
-))]
+#[utoipa::path(
+ put,
+ path = "/system/apply",
+ context_path = "/api/network",
+ responses(
+ (status = 204, description = "Apply configuration")
+ )
+)]
 async fn apply(
  State(state): State<NetworkServiceState>,
 ) -> Result<impl IntoResponse, NetworkError> {