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

aperture_cli/cache/
models.rs
