fix(rust): revamp the OpenAPI specification

.github/workflows/ci-rust.yml

@@ -76,6 +76,7 @@ jobs:
         openssl-3
         pam-devel
         python-langtable-data
+        python3-openapi_spec_validator
         timezone
         xkeyboard-config
 
@@ -101,6 +102,11 @@ jobs:
     - name: Run the tests
       run: cargo tarpaulin --out xml -- --nocapture
 
+    - name: Generate and validate the OpenAPI specification
+      run: |
+        cargo xtask openapi
+        openapi-spec-validator out/openapi/*
+
     # send the code coverage for the Rust part to the coveralls.io
     - name: Coveralls GitHub Action
       uses: coverallsapp/github-action@v2

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

@@ -27,14 +27,14 @@ use std::default::Default;
 use std::net::IpAddr;
 
 /// Network settings for installation
-#[derive(Debug, Default, Serialize, Deserialize)]
+#[derive(Debug, Default, Serialize, Deserialize, utoipa::ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct NetworkSettings {
     /// Connections to use in the installation
     pub connections: Vec<NetworkConnection>,
 }
 
-#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+#[derive(Clone, Debug, Default, Serialize, Deserialize, utoipa::ToSchema)]
 pub struct MatchSettings {
     #[serde(skip_serializing_if = "Vec::is_empty", default)]
     pub driver: Vec<String>,
@@ -56,7 +56,7 @@ impl MatchSettings {
 }
 
 /// Wireless configuration
-#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+#[derive(Clone, Debug, Default, Serialize, Deserialize, utoipa::ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct WirelessSettings {
     /// Password of the wireless network
@@ -94,7 +94,7 @@ pub struct WirelessSettings {
     pub pmf: i32,
 }
 
-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Clone, Debug, Serialize, Deserialize, utoipa::ToSchema)]
 pub struct BondSettings {
     pub mode: String,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -114,7 +114,7 @@ impl Default for BondSettings {
 }
 
 /// IEEE 802.1x (EAP) settings
-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Clone, Debug, Serialize, Deserialize, utoipa::ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct IEEE8021XSettings {
     /// List of EAP methods used

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

@@ -36,7 +36,7 @@ pub struct Device {
     pub state: DeviceState,
 }
 
-#[derive(Debug, Default, PartialEq, Clone, Serialize, Deserialize)]
+#[derive(Debug, Default, PartialEq, Clone, Serialize, Deserialize, utoipa::ToSchema)]
 pub struct SSID(pub Vec<u8>);
 
 impl SSID {
@@ -80,7 +80,7 @@ pub enum DeviceType {
 
 // For now this mirrors NetworkManager, because it was less mental work than coming up with
 // what exactly Agama needs. Expected to be adapted.
-#[derive(Debug, Default, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[derive(Debug, Default, Clone, Copy, PartialEq, Serialize, Deserialize, utoipa::ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub enum DeviceState {
     #[default]
@@ -145,7 +145,7 @@ impl fmt::Display for DeviceState {
     }
 }
 
-#[derive(Debug, Default, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[derive(Debug, Default, Clone, Copy, PartialEq, Serialize, Deserialize, utoipa::ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub enum Status {
     #[default]
@@ -183,7 +183,7 @@ impl TryFrom<&str> for Status {
 }
 
 /// Bond mode
-#[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, Copy)]
+#[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, Copy, utoipa::ToSchema)]
 pub enum BondMode {
     #[serde(rename = "balance-rr")]
     RoundRobin = 0,

rust/agama-lib/src/software/client.rs

@@ -43,7 +43,7 @@ pub struct Pattern {
 }
 
 /// Represents the reason why a pattern is selected.
-#[derive(Clone, Copy, Debug, PartialEq, Serialize_repr)]
+#[derive(Clone, Copy, Debug, PartialEq, Serialize_repr, utoipa::ToSchema)]
 #[repr(u8)]
 pub enum SelectedBy {
     /// The pattern was selected by the user.

rust/agama-locale-data/Cargo.toml

@@ -13,3 +13,4 @@ flate2 = "1.0.34"
 chrono-tz = "0.8.6"
 regex = "1"
 thiserror = "1.0.64"
+utoipa = "4.2.3"

rust/agama-locale-data/src/locale.rs

@@ -26,7 +26,7 @@ use std::sync::OnceLock;
 use std::{fmt::Display, str::FromStr};
 use thiserror::Error;
 
-#[derive(Clone, Debug, PartialEq, Serialize)]
+#[derive(Clone, Debug, PartialEq, Serialize, utoipa::ToSchema)]
 pub struct LocaleId {
     // ISO-639
     pub language: String,
@@ -100,9 +100,11 @@ static KEYMAP_ID_REGEX: OnceLock<Regex> = OnceLock::new();
 /// let id_with_dashes: KeymapId = "es-ast".parse().unwrap();
 /// assert_eq!(id, id_with_dashes);
 /// ```
-#[derive(Clone, Debug, PartialEq, Serialize)]
+#[derive(Clone, Debug, PartialEq, Serialize, utoipa::ToSchema)]
 pub struct KeymapId {
+    /// Keyboard layout (e.g., "es" in "es(ast)")
     pub layout: String,
+    /// Keyboard variante (e.g., "ast" in "es(ast)")
     pub variant: Option<String>,
 }
 

rust/agama-server/Cargo.toml

@@ -30,7 +30,7 @@ tracing-journald = "0.3.0"
 tracing = "0.1.40"
 clap = { version = "4.5.19", features = ["derive", "wrap_help"] }
 tower = { version = "0.4.13", features = ["util"] }
-utoipa = { version = "4.2.3", features = ["axum_extras"] }
+utoipa = { version = "4.2.0", features = ["axum_extras", "uuid"] }
 config = "0.14.0"
 rand = "0.8.5"
 axum-extra = { version = "0.9.4", features = ["cookie", "typed-header"] }

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

@@ -46,7 +46,6 @@ use openssl::ssl::{Ssl, SslAcceptor, SslMethod};
 use tokio::sync::broadcast::channel;
 use tokio_openssl::SslStream;
 use tower::Service;
-use utoipa::OpenApi;
 
 const DEFAULT_WEB_UI_DIR: &str = "/usr/share/agama/web_ui";
 const TOKEN_FILE: &str = "/run/agama/token";
@@ -58,8 +57,6 @@ enum Commands {
     /// This command starts the server in the given ports. The secondary port, if enabled, uses SSL.
     /// If no certificate is specified, agama-web-server generates a self-signed one.
     Serve(ServeArgs),
-    /// Generates the API documentation in OpenAPI format.
-    Openapi,
 }
 
 /// Manage Agama's HTTP/JSON API.
@@ -379,16 +376,9 @@ async fn serve_command(args: ServeArgs) -> anyhow::Result<()> {
     Ok(())
 }
 
-/// Display the API documentation in OpenAPI format.
-fn openapi_command() -> anyhow::Result<()> {
-    println!("{}", web::ApiDoc::openapi().to_pretty_json().unwrap());
-    Ok(())
-}
-
 async fn run_command(cli: Cli) -> anyhow::Result<()> {
     match cli.command {
         Commands::Serve(options) => serve_command(options).await,
-        Commands::Openapi => openapi_command(),
     }
 }