rustapi-openapi 0.1.450

Native OpenAPI 3.1 specification generator for RustAPI. Integrates Swagger UI.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

//! Standard error schemas for OpenAPI documentation
//!
//! These schemas match the error response format used by RustAPI.

use rustapi_macros::Schema;
use serde::{Deserialize, Serialize};

/// Standard error response body
#[derive(Debug, Clone, Serialize, Deserialize, Schema)]
pub struct ErrorSchema {
    /// The error details
    pub error: ErrorBodySchema,
    /// Optional request ID for tracing
    #[serde(skip_serializing_if = "Option::is_none")]
    pub request_id: Option<String>,
}

/// Error body details
#[derive(Debug, Clone, Serialize, Deserialize, Schema)]
pub struct ErrorBodySchema {
    /// Error type identifier (e.g., "validation_error", "not_found")
    #[serde(rename = "type")]
    pub error_type: String,
    /// Human-readable error message
    pub message: String,
    /// Field-level errors (for validation errors)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub fields: Option<Vec<FieldErrorSchema>>,
}

/// Field-level validation error
#[derive(Debug, Clone, Serialize, Deserialize, Schema)]
pub struct FieldErrorSchema {
    /// Field name (supports nested paths like "address.city")
    pub field: String,
    /// Error code (e.g., "email", "length", "required")
    pub code: String,
    /// Human-readable error message
    pub message: String,
}

/// Validation error response (422)
#[derive(Debug, Clone, Serialize, Deserialize, Schema)]
pub struct ValidationErrorSchema {
    /// Error wrapper
    pub error: ValidationErrorBodySchema,
}

/// Validation error body
#[derive(Debug, Clone, Serialize, Deserialize, Schema)]
pub struct ValidationErrorBodySchema {
    /// Always "validation_error" for validation errors
    #[serde(rename = "type")]
    pub error_type: String,
    /// Always "Request validation failed"
    pub message: String,
    /// List of field-level errors
    pub fields: Vec<FieldErrorSchema>,
}

impl ValidationErrorSchema {
    /// Create a sample validation error for documentation
    pub fn example() -> Self {
        Self {
            error: ValidationErrorBodySchema {
                error_type: "validation_error".to_string(),
                message: "Request validation failed".to_string(),
                fields: vec![FieldErrorSchema {
                    field: "email".to_string(),
                    code: "email".to_string(),
                    message: "Invalid email format".to_string(),
                }],
            },
        }
    }
}

impl ErrorSchema {
    /// Create a sample not found error
    pub fn not_found_example() -> Self {
        Self {
            error: ErrorBodySchema {
                error_type: "not_found".to_string(),
                message: "Resource not found".to_string(),
                fields: None,
            },
            request_id: None,
        }
    }

    /// Create a sample internal error
    pub fn internal_error_example() -> Self {
        Self {
            error: ErrorBodySchema {
                error_type: "internal_error".to_string(),
                message: "An internal error occurred".to_string(),
                fields: None,
            },
            request_id: None,
        }
    }

    /// Create a sample bad request error
    pub fn bad_request_example() -> Self {
        Self {
            error: ErrorBodySchema {
                error_type: "bad_request".to_string(),
                message: "Invalid request".to_string(),
                fields: None,
            },
            request_id: None,
        }
    }
}