feat: added openapi generation for agent

apps/agent/src/main.rs

@@ -1,6 +1,7 @@
 #![forbid(unsafe_code)]
 
 mod commands;
+mod openapi;
 mod routes;
 
 use axum::routing::get;
@@ -13,6 +14,7 @@ use tokio::net::UnixListener;
 use tracing::{error, info, warn};
 
 use crate::commands::NginxService;
+use crate::openapi::{GenerateOpenapiArgs, generate_openapi_doc};
 use crate::routes::{status, validate, validate_and_reload, write_config};
 
 const SOCK_ENV: &str = "YANPM_AGENT_SOCK";
@@ -43,6 +45,19 @@ struct Args {
     /// GID to set on the unix socket, default: current user's primary group
     #[arg(long, default_value_t = String::from(SOCK_GID_DEFAULT), env = SOCK_GID_ENV)]
     sock_gid: String,
+
+    #[command(subcommand)]
+    command: Option<SubCommand>,
+}
+
+#[derive(clap::Subcommand, Debug)]
+pub enum SubCommand {
+    /// Generate OpenAPI spec to file or stdout
+    GenerateOpenapi {
+        /// Output file path.
+        #[arg(short = 'o', long)]
+        output: String,
+    },
 }
 
 #[tokio::main]
@@ -59,6 +74,18 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 
     let args = Args::parse();
 
+    if let Some(cmd) = &args.command {
+        match cmd {
+            SubCommand::GenerateOpenapi { output } => {
+                generate_openapi_doc(&GenerateOpenapiArgs {
+                    output: output.clone(),
+                })
+                .await?;
+                return Ok(());
+            }
+        }
+    }
+
     let (sock, nginx_config_dir, sock_perm, sock_gid) = get_args(&args).await?;
 
     let path = PathBuf::from(&sock);

apps/agent/src/openapi.rs

@@ -0,0 +1,45 @@
+use tracing::info;
+use utoipa::OpenApi;
+
+pub mod tag {
+    /// nginx
+    pub const NGINX_TAG: &str = "Nginx Agent";
+}
+
+#[derive(utoipa::OpenApi)]
+#[openapi(
+  paths(
+    crate::routes::status,
+    crate::routes::validate,
+    crate::routes::validate_and_reload,
+    crate::routes::write_config,
+  ),
+  components(
+      schemas(crate::routes::StatusResp),
+      schemas(crate::routes::ValidateAndReloadResp),
+      schemas(crate::routes::ValidateBody),
+      schemas(crate::routes::WriteConfigBody),
+      schemas(crate::routes::ValidateAndReloadBody),
+  ),
+  tags(
+      (name = tag::NGINX_TAG, description = "Nginx Agent API"),
+  )
+)]
+struct ApiDoc;
+
+pub struct GenerateOpenapiArgs {
+    pub output: String,
+}
+
+pub async fn generate_openapi_doc(
+    args: &GenerateOpenapiArgs,
+) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    info!("Generating OpenAPI documentation...");
+    let doc = ApiDoc::openapi();
+    let json = doc
+        .to_pretty_json()
+        .expect("Failed to serialize OpenAPI doc to JSON");
+    std::fs::write(&args.output, json).expect("Failed to write OpenAPI doc to file");
+    info!("OpenAPI documentation generated at {}", args.output);
+    Ok(())
+}

apps/agent/src/routes.rs

@@ -9,28 +9,46 @@ use tracing::warn;
 
 use crate::commands::NginxService;
 
-#[derive(Serialize)]
+#[derive(Serialize, utoipa::ToSchema)]
 pub struct StatusResp {
     pub ok: bool,
 }
 
+/// Health check endpoint
+#[utoipa::path(
+    get,
+    path = "/status",
+    responses(
+        (status = 200, description = "Status response", body = StatusResp)
+    ),
+    tag = crate::openapi::tag::NGINX_TAG
+)]
 pub async fn status() -> impl IntoResponse {
     let resp = StatusResp { ok: true };
     (axum::http::StatusCode::OK, axum::Json(resp))
 }
 
-#[derive(Serialize)]
+#[derive(Serialize, utoipa::ToSchema)]
 pub struct ValidateAndReloadResp {
     pub rc: i32,
     pub ro: String,
 }
 
-#[derive(Deserialize)]
+#[derive(Deserialize, utoipa::ToSchema)]
 pub struct ValidateBody {
     config_name: String,
     timestamp: u64,
 }
 
+#[utoipa::path(
+    post,
+    path = "/validate",
+    request_body = ValidateBody,
+    responses(
+        (status = 200, description = "Validation response", body = serde_json::Value)
+    ),
+    tag = crate::openapi::tag::NGINX_TAG
+)]
 pub async fn validate(
     State(nginx_controller): State<Arc<NginxService>>,
     Json(payload): Json<Value>,
@@ -57,12 +75,21 @@ pub async fn validate(
     (axum::http::StatusCode::OK, axum::Json(resp)).into_response()
 }
 
-#[derive(Deserialize)]
+#[derive(Deserialize, utoipa::ToSchema)]
 pub struct ValidateAndReloadBody {
     config_name: String,
     timestamp: u64,
 }
 
+#[utoipa::path(
+    post,
+    path = "/validate_and_reload",
+    request_body = ValidateAndReloadBody,
+    responses(
+        (status = 200, description = "Validate and reload response", body = ValidateAndReloadResp)
+    ),
+    tag = crate::openapi::tag::NGINX_TAG
+)]
 pub async fn validate_and_reload(
     State(nginx_controller): State<Arc<NginxService>>,
     Json(payload): Json<Value>,
@@ -96,13 +123,23 @@ pub async fn validate_and_reload(
     (axum::http::StatusCode::OK, axum::Json(resp)).into_response()
 }
 
-#[derive(Deserialize)]
+#[derive(Deserialize, utoipa::ToSchema)]
 pub struct WriteConfigBody {
     config_name: String,
     timestamp: u64,
     content: String,
 }
 
+#[utoipa::path(
+    post,
+    path = "/write_config",
+    request_body = WriteConfigBody,
+    responses(
+        (status = 200, description = "Write config response"),
+        (status = 500, description = "Internal server error", body = serde_json::Value)
+    ),
+    tag = crate::openapi::tag::NGINX_TAG
+)]
 pub async fn write_config(
     State(nginx_controller): State<Arc<NginxService>>,
     Json(payload): Json<Value>,