From 34ebfaddbc91b2d9984b43683d253684469a04a3 Mon Sep 17 00:00:00 2001
From: GW_MC <72297530+GWMCwing@users.noreply.github.com>
Date: Fri, 5 Dec 2025 17:01:29 +0800
Subject: [PATCH] Add OpenAPI support and health info endpoint documentation

---
 Cargo.lock                             | 26 ++++++++++++++++++++++++++
 apps/api/Cargo.toml                    |  1 +
 apps/api/src/routes.rs                 |  2 ++
 apps/api/src/routes/api.rs             |  3 +++
 apps/api/src/routes/api/health.rs      |  2 +-
 apps/api/src/routes/api/health/info.rs | 13 ++++++++++++-
 apps/api/src/routes/api/openapi.rs     |  3 +++
 7 files changed, 48 insertions(+), 2 deletions(-)
 create mode 100644 apps/api/src/routes/api/openapi.rs

diff --git a/Cargo.lock b/Cargo.lock
index ab8dd37..71af87e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3820,6 +3820,31 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
+[[package]]
+name = "utoipa"
+version = "5.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2fcc29c80c21c31608227e0912b2d7fddba57ad76b606890627ba8ee7964e993"
+dependencies = [
+ "indexmap 2.12.0",
+ "serde",
+ "serde_json",
+ "utoipa-gen",
+]
+
+[[package]]
+name = "utoipa-gen"
+version = "5.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d79d08d92ab8af4c5e8a6da20c47ae3f61a0f1dabc1997cdf2d082b757ca08b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "regex",
+ "syn 2.0.110",
+ "uuid",
+]
+
 [[package]]
 name = "uuid"
 version = "1.18.1"
@@ -4340,6 +4365,7 @@ dependencies = [
  "tower",
  "tracing",
  "tracing-subscriber",
+ "utoipa",
 ]
 
 [[package]]
diff --git a/apps/api/Cargo.toml b/apps/api/Cargo.toml
index c4c76d4..3d132ad 100644
--- a/apps/api/Cargo.toml
+++ b/apps/api/Cargo.toml
@@ -20,3 +20,4 @@ serde = { version = "1.0.228", features = ["std", "derive"] }
 sea-orm = { workspace = true }
 include_dir = { version = "0.7.4" }
 mime_guess = { version = "2.0.5" }
+utoipa = { version = "5.4.0", features = ["macros", "axum_extras", "chrono", "decimal", "uuid", "time", "openapi_extensions"] }
diff --git a/apps/api/src/routes.rs b/apps/api/src/routes.rs
index 7fb0e6b..f257f1b 100644
--- a/apps/api/src/routes.rs
+++ b/apps/api/src/routes.rs
@@ -1,6 +1,8 @@
 mod api;
 mod view;
 
+pub use self::api::ApiDoc;
+
 use std::sync::Arc;
 
 use axum::{Extension, Router};
diff --git a/apps/api/src/routes/api.rs b/apps/api/src/routes/api.rs
index 7f648a2..68bbdcc 100644
--- a/apps/api/src/routes/api.rs
+++ b/apps/api/src/routes/api.rs
@@ -1,4 +1,7 @@
 mod health;
+mod openapi;
+
+pub use self::openapi::ApiDoc;
 
 use axum::{Router, response::IntoResponse, routing::any};
 
diff --git a/apps/api/src/routes/api/health.rs b/apps/api/src/routes/api/health.rs
index 98f6b15..b6cc7bc 100644
--- a/apps/api/src/routes/api/health.rs
+++ b/apps/api/src/routes/api/health.rs
@@ -1,4 +1,4 @@
-mod info;
+pub mod info;
 mod state;
 
 use std::sync::Arc;
diff --git a/apps/api/src/routes/api/health/info.rs b/apps/api/src/routes/api/health/info.rs
index 0e09d93..3299f5b 100644
--- a/apps/api/src/routes/api/health/info.rs
+++ b/apps/api/src/routes/api/health/info.rs
@@ -9,7 +9,7 @@ use crate::routes::api::health::state::HealthState;
 const STATUS_HEALTHY: &str = "healthy";
 const STATUS_UNHEALTHY: &str = "unhealthy";
 
-#[derive(Serialize, Deserialize)]
+#[derive(Serialize, Deserialize, utoipa::ToSchema)]
 pub struct HealthInfo {
     pub status: String,
     pub version: String,
@@ -18,6 +18,17 @@ pub struct HealthInfo {
     pub errors: Option<Vec<String>>,
 }
 
+#[utoipa::path(
+        get,
+        path = "/api/health/info",
+        responses(
+            (status = 200, description = "Health information retrieved successfully", body = HealthInfo),
+            (status = NOT_FOUND, description = "Health information not found")
+        ),
+        params(
+            ("id" = u64, Path, description = "Pet database id to get Pet for"),
+        )
+    )]
 pub async fn get_health_info(
     State(state): State<Arc<HealthState>>,
 ) -> (StatusCode, Json<HealthInfo>) {
diff --git a/apps/api/src/routes/api/openapi.rs b/apps/api/src/routes/api/openapi.rs
new file mode 100644
index 0000000..cd6d8f3
--- /dev/null
+++ b/apps/api/src/routes/api/openapi.rs
@@ -0,0 +1,3 @@
+#[derive(utoipa::OpenApi)]
+#[openapi(paths(crate::routes::api::health::info::get_health_info))]
+pub struct ApiDoc;