Add OpenAPI/Swagger documentation with utoipa for auth and user endpoints

Co-authored-by: ngocbd <439333+ngocbd@users.noreply.github.com>

Author: Copilot

Cargo.toml

@@ -62,6 +62,10 @@ regex = "1.0"
 kube = { version = "0.95", features = ["runtime", "derive"] }
 k8s-openapi = { version = "0.23", features = ["latest"] }
 
+# OpenAPI documentation
+utoipa = { version = "4.0", features = ["axum_extras", "chrono", "uuid"] }
+utoipa-swagger-ui = { version = "4.0", features = ["axum"] }
+
 [dev-dependencies]
 tower-test = "0.4"
 tempfile = "3.0"

src/auth/models.rs

@@ -1,27 +1,30 @@
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 use sqlx::FromRow;
+use utoipa::ToSchema;
 use uuid::Uuid;
 use validator::Validate;
 
-#[derive(Debug, Clone, FromRow, Serialize, Deserialize)]
+#[derive(Debug, Clone, FromRow, Serialize, Deserialize, ToSchema)]
 pub struct User {
     pub id: Uuid,
     pub username: String,
     pub email: String,
+    #[serde(skip_serializing)]
     pub password_hash: String,
     pub created_at: DateTime<Utc>,
     pub updated_at: DateTime<Utc>,
     pub last_login: Option<DateTime<Utc>>,
     pub is_active: bool,
 }
 
-#[derive(Debug, Clone, FromRow, Serialize, Deserialize)]
+#[derive(Debug, Clone, FromRow, Serialize, Deserialize, ToSchema)]
 pub struct ApiKey {
     pub id: Uuid,
     pub user_id: Uuid,
     pub name: String,
     pub description: Option<String>,
+    #[serde(skip_serializing)]
     pub key_hash: String,
     pub key_prefix: String,
     pub created_at: DateTime<Utc>,
@@ -30,71 +33,88 @@ pub struct ApiKey {
     pub is_active: bool,
 }
 
-#[derive(Debug, Deserialize, Validate)]
+#[derive(Debug, Deserialize, Validate, ToSchema)]
 pub struct RegisterRequest {
+    /// Username must be between 3 and 50 characters
     #[validate(length(min = 3, max = 50))]
     pub username: String,
+    /// Valid email address
     #[validate(email)]
     pub email: String,
+    /// Password must be at least 8 characters
     #[validate(length(min = 8))]
     pub password: String,
+    /// Must match the password field
     pub confirm_password: String,
 }
 
-#[derive(Debug, Deserialize, Validate)]
+#[derive(Debug, Deserialize, Validate, ToSchema)]
 pub struct LoginRequest {
+    /// Valid email address
     #[validate(email)]
     pub email: String,
+    /// User password
     pub password: String,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct AuthResponse {
+    /// JWT access token
     pub access_token: String,
+    /// JWT refresh token
     pub refresh_token: String,
+    /// Token expiration timestamp
     pub expires_at: DateTime<Utc>,
+    /// User information
     pub user: UserInfo,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct UserInfo {
     pub id: Uuid,
     pub username: String,
     pub email: String,
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, ToSchema)]
 pub struct RefreshTokenRequest {
+    /// JWT refresh token
     pub refresh_token: String,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct RefreshTokenResponse {
+    /// New JWT access token
     pub access_token: String,
+    /// New token expiration timestamp
     pub expires_at: DateTime<Utc>,
 }
 
-#[derive(Debug, Deserialize, Validate)]
+#[derive(Debug, Deserialize, Validate, ToSchema)]
 pub struct CreateApiKeyRequest {
+    /// API key name (1-100 characters)
     #[validate(length(min = 1, max = 100))]
     pub name: String,
+    /// Optional description (max 255 characters)
     #[validate(length(max = 255))]
     pub description: Option<String>,
+    /// Optional expiration date
     pub expires_at: Option<DateTime<Utc>>,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct ApiKeyResponse {
     pub id: Uuid,
     pub name: String,
     pub description: Option<String>,
+    /// The actual API key (only shown once during creation)
     pub api_key: String,
     pub created_at: DateTime<Utc>,
     pub expires_at: Option<DateTime<Utc>>,
     pub last_used: Option<DateTime<Utc>>,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct ApiKeyListItem {
     pub id: Uuid,
     pub name: String,
@@ -104,13 +124,13 @@ pub struct ApiKeyListItem {
     pub last_used: Option<DateTime<Utc>>,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct ApiKeyListResponse {
     pub api_keys: Vec<ApiKeyListItem>,
     pub pagination: PaginationInfo,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct PaginationInfo {
     pub page: u32,
     pub limit: u32,

src/deployment/models.rs

@@ -4,10 +4,11 @@ use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use sqlx::FromRow;
 use std::collections::HashMap;
+use utoipa::ToSchema;
 use uuid::Uuid;
 use validator::Validate;
 
-#[derive(Debug, Clone, FromRow, Serialize, Deserialize)]
+#[derive(Debug, Clone, FromRow, Serialize, Deserialize, ToSchema)]
 pub struct Deployment {
     pub id: Uuid,
     pub user_id: Uuid,
@@ -25,49 +26,66 @@ pub struct Deployment {
     pub deployed_at: Option<DateTime<Utc>>,
 }
 
-#[derive(Debug, Deserialize, Validate)]
+#[derive(Debug, Deserialize, Validate, ToSchema)]
 pub struct CreateDeploymentRequest {
+    /// Application name (1-63 characters, DNS-compatible)
     #[validate(length(min = 1, max = 63))]
     pub app_name: String,
+    /// Container image URL
     #[validate(length(min = 1))]
     pub image: String,
+    /// Port number the container listens on (1-65535)
     #[validate(range(min = 1, max = 65535))]
     pub port: i32,
+    /// Environment variables
     pub env_vars: Option<HashMap<String, String>>,
+    /// Number of replicas (1-100)
     #[validate(range(min = 1, max = 100))]
     pub replicas: Option<i32>,
+    /// Resource requirements
     pub resources: Option<ResourceRequirements>,
+    /// Health check configuration
     pub health_check: Option<HealthCheck>,
+    /// Registry authentication (if required)
     pub registry_auth: Option<RegistryAuth>,
 }
 
-#[derive(Debug, Serialize, Deserialize, Validate, Default)]
+#[derive(Debug, Serialize, Deserialize, Validate, Default, ToSchema)]
 pub struct ResourceRequirements {
+    /// CPU request/limit (e.g., "100m", "0.5")
     pub cpu: Option<String>,
+    /// Memory request/limit (e.g., "128Mi", "1Gi")
     pub memory: Option<String>,
 }
 
-#[derive(Debug, Serialize, Deserialize, Validate)]
+#[derive(Debug, Serialize, Deserialize, Validate, ToSchema)]
 pub struct HealthCheck {
+    /// Health check endpoint path
     #[validate(length(min = 1))]
     pub path: String,
+    /// Initial delay before first health check (0-300 seconds)
     #[validate(range(min = 0, max = 300))]
     pub initial_delay_seconds: Option<i32>,
+    /// Interval between health checks (1-300 seconds)
     #[validate(range(min = 1, max = 300))]
     pub period_seconds: Option<i32>,
+    /// Timeout for each health check (1-60 seconds)
     #[validate(range(min = 1, max = 60))]
     pub timeout_seconds: Option<i32>,
+    /// Number of failures before marking unhealthy (1-10)
     #[validate(range(min = 1, max = 10))]
     pub failure_threshold: Option<i32>,
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, ToSchema)]
 pub struct RegistryAuth {
+    /// Registry username
     pub username: String,
+    /// Registry password
     pub password: String,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct DeploymentResponse {
     pub id: Uuid,
     pub app_name: String,
@@ -78,7 +96,7 @@ pub struct DeploymentResponse {
     pub message: String,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct DeploymentListItem {
     pub id: Uuid,
     pub app_name: String,
@@ -90,75 +108,87 @@ pub struct DeploymentListItem {
     pub updated_at: DateTime<Utc>,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct DeploymentListResponse {
     pub deployments: Vec<DeploymentListItem>,
     pub pagination: PaginationInfo,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct PaginationInfo {
     pub page: u32,
     pub limit: u32,
     pub total: u64,
     pub total_pages: u32,
 }
 
-#[derive(Debug, Deserialize, Validate)]
+#[derive(Debug, Deserialize, Validate, ToSchema)]
 pub struct UpdateDeploymentRequest {
+    /// New container image
     pub image: Option<String>,
+    /// Updated environment variables
     pub env_vars: Option<HashMap<String, String>>,
+    /// New replica count (1-100)
     #[validate(range(min = 1, max = 100))]
     pub replicas: Option<i32>,
+    /// Updated resource requirements
     pub resources: Option<ResourceRequirements>,
 }
 
-#[derive(Debug, Deserialize, Validate)]
+#[derive(Debug, Deserialize, Validate, ToSchema)]
 pub struct ScaleDeploymentRequest {
+    /// Number of replicas (0-100)
     #[validate(range(min = 0, max = 100))]
     pub replicas: i32,
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, ToSchema)]
 pub struct LogsQuery {
+    /// Number of lines to show from the end
     pub tail: Option<i32>,
+    /// Follow log output (streaming)
     pub follow: Option<bool>,
+    /// Show logs after this timestamp
     pub since: Option<DateTime<Utc>>,
+    /// Show logs before this timestamp
     pub until: Option<DateTime<Utc>>,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct LogEntry {
     pub timestamp: DateTime<Utc>,
     pub level: String,
     pub message: String,
     pub source: String,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct LogsResponse {
     pub logs: Vec<LogEntry>,
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, ToSchema)]
 pub struct MetricsQuery {
+    /// Start time for metrics
     pub from: Option<DateTime<Utc>>,
+    /// End time for metrics
     pub to: Option<DateTime<Utc>>,
+    /// Metrics resolution
     pub resolution: Option<String>,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct MetricPoint {
     pub timestamp: DateTime<Utc>,
     pub value: f64,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct MetricsResponse {
     pub metrics: HashMap<String, Vec<MetricPoint>>,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct DeploymentStatus {
     pub status: String,
     pub health: String,
@@ -168,20 +198,21 @@ pub struct DeploymentStatus {
     pub restart_count: i32,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct ReplicaStatus {
     pub desired: i32,
     pub ready: i32,
     pub available: i32,
 }
 
-#[derive(Debug, Deserialize, Validate)]
+#[derive(Debug, Deserialize, Validate, ToSchema)]
 pub struct AddDomainRequest {
+    /// Custom domain name (1-253 characters)
     #[validate(length(min = 1, max = 253))]
     pub domain: String,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct DomainResponse {
     pub id: Uuid,
     pub domain: String,
@@ -190,19 +221,19 @@ pub struct DomainResponse {
     pub dns_records: Vec<DnsRecord>,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct DnsRecord {
     pub record_type: String,
     pub name: String,
     pub value: String,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct DomainListResponse {
     pub domains: Vec<DomainListItem>,
 }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, Serialize, ToSchema)]
 pub struct DomainListItem {
     pub id: Uuid,
     pub domain: String,