aperture_cli/cache/
models.rs

1use serde::{Deserialize, Serialize};
2use std::collections::HashMap;
3
4#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
5pub struct CachedSpec {
6    /// Cache format version to detect incompatible changes
7    pub cache_format_version: u32,
8    pub name: String,
9    pub version: String,
10    pub commands: Vec<CachedCommand>,
11    /// Base URL extracted from the first server in the `OpenAPI` spec
12    pub base_url: Option<String>,
13    /// All server URLs from the `OpenAPI` spec for future multi-environment support
14    pub servers: Vec<String>,
15    /// Security schemes defined in the `OpenAPI` spec with `x-aperture-secret` mappings
16    pub security_schemes: HashMap<String, CachedSecurityScheme>,
17    /// Endpoints skipped during validation due to unsupported features (added in v0.1.2)
18    #[serde(default)]
19    pub skipped_endpoints: Vec<SkippedEndpoint>,
20    /// Server variables defined in the `OpenAPI` spec for URL template resolution (added in v0.1.3)
21    #[serde(default)]
22    pub server_variables: HashMap<String, ServerVariable>,
23}
24
25impl CachedSpec {
26    /// Creates a new `CachedSpec` with default values for testing
27    #[cfg(test)]
28    #[must_use]
29    pub fn new_for_test(name: &str) -> Self {
30        Self {
31            cache_format_version: CACHE_FORMAT_VERSION,
32            name: name.to_string(),
33            version: "1.0.0".to_string(),
34            commands: vec![],
35            base_url: None,
36            servers: vec![],
37            security_schemes: HashMap::new(),
38            skipped_endpoints: vec![],
39            server_variables: HashMap::new(),
40        }
41    }
42}
43
44/// Example usage for a command
45#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
46pub struct CommandExample {
47    /// Brief description of what this example demonstrates
48    pub description: String,
49    /// The complete command line example
50    pub command_line: String,
51    /// Optional explanation of the parameters used
52    pub explanation: Option<String>,
53}
54
55/// Information about an endpoint that was skipped during spec validation
56#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
57pub struct SkippedEndpoint {
58    pub path: String,
59    pub method: String,
60    pub content_type: String,
61    pub reason: String,
62}
63
64/// Current cache format version - increment when making breaking changes to `CachedSpec`
65///
66/// Version 2: Added `skipped_endpoints` field to track endpoints skipped during validation
67/// Version 3: Added `server_variables` field to support `OpenAPI` server URL template variables
68/// Version 4: Added `example` field to `CachedResponse` for response schema examples
69pub const CACHE_FORMAT_VERSION: u32 = 4;
70
71/// Global cache metadata for all cached specifications
72#[derive(Debug, Deserialize, Serialize, PartialEq, Eq)]
73pub struct GlobalCacheMetadata {
74    /// Cache format version for all specs
75    pub cache_format_version: u32,
76    /// Individual spec metadata
77    pub specs: std::collections::HashMap<String, SpecMetadata>,
78}
79
80/// Metadata for a single cached specification
81#[derive(Debug, Deserialize, Serialize, PartialEq, Eq, Clone)]
82pub struct SpecMetadata {
83    /// When this spec cache was created/updated
84    pub updated_at: String, // Using String for simplicity in serialization
85    /// Size of the cached spec file in bytes
86    pub file_size: u64,
87}
88
89impl Default for GlobalCacheMetadata {
90    fn default() -> Self {
91        Self {
92            cache_format_version: CACHE_FORMAT_VERSION,
93            specs: std::collections::HashMap::new(),
94        }
95    }
96}
97
98#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
99pub struct CachedCommand {
100    pub name: String,
101    pub description: Option<String>,
102    pub summary: Option<String>,
103    pub operation_id: String,
104    pub method: String,
105    pub path: String,
106    pub parameters: Vec<CachedParameter>,
107    pub request_body: Option<CachedRequestBody>,
108    pub responses: Vec<CachedResponse>,
109    /// Security requirements for this operation (references to security scheme names)
110    pub security_requirements: Vec<String>,
111    /// All tags associated with this operation
112    pub tags: Vec<String>,
113    /// Whether this operation is deprecated
114    pub deprecated: bool,
115    /// External documentation URL if available
116    pub external_docs_url: Option<String>,
117    /// Usage examples for this command (added in v0.1.6)
118    #[serde(default)]
119    pub examples: Vec<CommandExample>,
120}
121
122#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
123pub struct CachedParameter {
124    pub name: String,
125    pub location: String,
126    pub required: bool,
127    pub description: Option<String>,
128    pub schema: Option<String>,
129    pub schema_type: Option<String>,
130    pub format: Option<String>,
131    pub default_value: Option<String>,
132    pub enum_values: Vec<String>,
133    pub example: Option<String>,
134}
135
136#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
137pub struct CachedRequestBody {
138    pub content_type: String,
139    pub schema: String,
140    pub required: bool,
141    pub description: Option<String>,
142    pub example: Option<String>,
143}
144
145#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
146pub struct CachedResponse {
147    pub status_code: String,
148    pub description: Option<String>,
149    pub content_type: Option<String>,
150    pub schema: Option<String>,
151    /// Example response value (JSON-serialized)
152    #[serde(default)]
153    pub example: Option<String>,
154}
155
156/// Cached representation of a security scheme with x-aperture-secret mapping
157#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
158pub struct CachedSecurityScheme {
159    /// Security scheme name from the `OpenAPI` spec
160    pub name: String,
161    /// Type of security scheme (apiKey, http, oauth2, etc.)
162    pub scheme_type: String,
163    /// Subtype for http schemes (bearer, basic, etc.)
164    pub scheme: Option<String>,
165    /// Location for apiKey schemes (header, query, cookie)
166    pub location: Option<String>,
167    /// Parameter name for apiKey schemes (e.g., "Authorization", "X-API-Key")
168    pub parameter_name: Option<String>,
169    /// Description of the security scheme from `OpenAPI` spec
170    pub description: Option<String>,
171    /// Bearer format for HTTP bearer schemes (e.g., "JWT")
172    pub bearer_format: Option<String>,
173    /// x-aperture-secret mapping for environment variable resolution
174    pub aperture_secret: Option<CachedApertureSecret>,
175}
176
177/// Cached representation of x-aperture-secret extension
178#[derive(Debug, Deserialize, Serialize, PartialEq, Eq, Clone)]
179pub struct CachedApertureSecret {
180    /// Source of the secret (currently only "env" supported)
181    pub source: String,
182    /// Environment variable name to read the secret from
183    pub name: String,
184}
185
186/// Cached representation of an `OpenAPI` server variable for URL template resolution
187#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
188pub struct ServerVariable {
189    /// Default value for the variable if not provided via CLI
190    pub default: Option<String>,
191    /// Allowed values for the variable (enum constraint)
192    pub enum_values: Vec<String>,
193    /// Description of the server variable from `OpenAPI` spec
194    pub description: Option<String>,
195}
aperture_cli/cache/models.rs

aperture_cli/cache/
models.rs
