Refactor health check API to include OpenAPI tagging and enhance HealthInfo schema documentation

apps/api/src/routes/api/health/info.rs

@@ -4,20 +4,27 @@ use axum::{Json, extract::State, http::StatusCode};
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 
-use crate::routes::api::health::state::HealthState;
+use crate::routes::api::{health::state::HealthState, openapi::tag::HEALTH_TAG};
 
 const STATUS_HEALTHY: &str = "healthy";
 const STATUS_UNHEALTHY: &str = "unhealthy";
 
+/// System health information
 #[derive(Serialize, Deserialize, utoipa::ToSchema)]
 pub struct HealthInfo {
+    /// Health status: "healthy" or "unhealthy"
     pub status: String,
+    /// Application version
     pub version: String,
-    // RFC 3339 formatted timestamp
+    /// RFC 3339 formatted timestamp
     pub up_since: DateTime<Utc>,
+    /// List of error messages if unhealthy
     pub errors: Option<Vec<String>>,
 }
 
+/// Health check endpoint
+///
+/// Returns the health status, version, uptime, and any errors if unhealthy.
 #[utoipa::path(
         get,
         path = "/api/health/info",
@@ -25,9 +32,7 @@ pub struct HealthInfo {
             (status = 200, description = "Health information retrieved successfully", body = HealthInfo),
             (status = NOT_FOUND, description = "Health information not found")
         ),
-        params(
+        tag = HEALTH_TAG,
-            ("id" = u64, Path, description = "Pet database id to get Pet for"),
-        )
     )]
 pub async fn get_health_info(
     State(state): State<Arc<HealthState>>,

apps/api/src/routes/api/openapi.rs

@@ -1,3 +1,18 @@
+pub mod tag {
+    /// Health tag constant
+    pub const HEALTH_TAG: &str = "Health";
+}
+
 #[derive(utoipa::OpenApi)]
-#[openapi(paths(crate::routes::api::health::info::get_health_info))]
+#[openapi(
+  paths(
+    crate::routes::api::health::info::get_health_info
+  ),
+  components(
+      schemas(crate::routes::api::health::info::HealthInfo) // Register any schemas used in your paths
+  ),
+  tags(
+      (name = tag::HEALTH_TAG, description = "Health information API")
+  )
+)]
 pub struct ApiDoc;

apps/api/swagger.json

@@ -12,22 +12,11 @@
     "/api/health/info": {
       "get": {
         "tags": [
-          "crate::routes::api::health::info"
+          "Health"
         ],
+        "summary": "Health check endpoint",
+        "description": "Returns the health status, version, uptime, and any errors if unhealthy.",
         "operationId": "get_health_info",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "description": "Pet database id to get Pet for",
-            "required": true,
-            "schema": {
-              "type": "integer",
-              "format": "int64",
-              "minimum": 0
-            }
-          }
-        ],
         "responses": {
           "200": {
             "description": "Health information retrieved successfully",
@@ -50,6 +39,7 @@
     "schemas": {
       "HealthInfo": {
         "type": "object",
+        "description": "System health information",
         "required": [
           "status",
           "version",
@@ -63,20 +53,30 @@
             ],
             "items": {
               "type": "string"
-            }
+            },
+            "description": "List of error messages if unhealthy"
           },
           "status": {
-            "type": "string"
+            "type": "string",
+            "description": "Health status: \"healthy\" or \"unhealthy\""
           },
           "up_since": {
             "type": "string",
-            "format": "date-time"
+            "format": "date-time",
+            "description": "RFC 3339 formatted timestamp"
           },
           "version": {
-            "type": "string"
+            "type": "string",
+            "description": "Application version"
           }
         }
       }
     }
-  }
+  },
+  "tags": [
+    {
+      "name": "Health",
+      "description": "Health information API"
+    }
+  ]
 }