mockforge_core/openapi/
spec.rs

1//! OpenAPI specification loading and parsing
2//!
3//! This module handles loading OpenAPI specifications from files,
4//! parsing them, and providing basic operations on the specs.
5//! It also supports Swagger 2.0 specifications by converting them
6//! to OpenAPI 3.0 format automatically.
7
8use crate::openapi::swagger_convert;
9use crate::{Error, Result};
10use openapiv3::{OpenAPI, ReferenceOr, Schema};
11use std::collections::HashSet;
12use std::path::Path;
13use tokio::fs;
14use tracing;
15
16/// OpenAPI specification loader and parser
17#[derive(Debug, Clone)]
18pub struct OpenApiSpec {
19    /// The parsed OpenAPI specification
20    pub spec: OpenAPI,
21    /// Path to the original spec file
22    pub file_path: Option<String>,
23    /// Raw OpenAPI document preserved as JSON for resolving unsupported constructs
24    pub raw_document: Option<serde_json::Value>,
25}
26
27impl OpenApiSpec {
28    /// Load OpenAPI spec from a file path
29    ///
30    /// Supports both OpenAPI 3.x and Swagger 2.0 specifications.
31    /// Swagger 2.0 specs are automatically converted to OpenAPI 3.0 format.
32    pub async fn from_file<P: AsRef<Path>>(path: P) -> Result<Self> {
33        let path_ref = path.as_ref();
34        let content = fs::read_to_string(path_ref)
35            .await
36            .map_err(|e| Error::io_with_context("reading OpenAPI spec file", e.to_string()))?;
37
38        let raw_json = if path_ref.extension().and_then(|s| s.to_str()) == Some("yaml")
39            || path_ref.extension().and_then(|s| s.to_str()) == Some("yml")
40        {
41            let yaml_value: serde_yaml::Value = serde_yaml::from_str(&content)
42                .map_err(|e| Error::config(format!("Failed to parse YAML OpenAPI spec: {}", e)))?;
43            serde_json::to_value(&yaml_value).map_err(|e| {
44                Error::config(format!("Failed to convert YAML OpenAPI spec to JSON: {}", e))
45            })?
46        } else {
47            serde_json::from_str(&content)
48                .map_err(|e| Error::config(format!("Failed to parse JSON OpenAPI spec: {}", e)))?
49        };
50
51        // Check if this is a Swagger 2.0 spec and convert if necessary
52        let (raw_document, spec) = if swagger_convert::is_swagger_2(&raw_json) {
53            tracing::info!("Detected Swagger 2.0 specification, converting to OpenAPI 3.0");
54            let converted =
55                swagger_convert::convert_swagger_to_openapi3(&raw_json).map_err(|e| {
56                    Error::config(format!("Failed to convert Swagger 2.0 to OpenAPI 3.0: {}", e))
57                })?;
58            let spec: OpenAPI = serde_json::from_value(converted.clone()).map_err(|e| {
59                Error::config(format!("Failed to parse converted OpenAPI spec: {}", e))
60            })?;
61            (converted, spec)
62        } else {
63            let spec: OpenAPI = serde_json::from_value(raw_json.clone()).map_err(|e| {
64                // Enhanced error reporting for debugging missing field errors
65                let error_str = format!("{}", e);
66                let mut error_msg = format!("Failed to read OpenAPI spec: {}", e);
67
68                // If it's a missing field error, add diagnostic information
69                if error_str.contains("missing field") {
70                    tracing::error!("OpenAPI deserialization error: {}", error_str);
71
72                    // Add context about the spec structure
73                    if let Some(info) = raw_json.get("info") {
74                        if let Some(info_obj) = info.as_object() {
75                            let has_desc = info_obj.contains_key("description");
76                            error_msg
77                                .push_str(&format!(" | Info.description present: {}", has_desc));
78                        }
79                    }
80                    if let Some(servers) = raw_json.get("servers") {
81                        if let Some(servers_arr) = servers.as_array() {
82                            error_msg.push_str(&format!(" | Servers count: {}", servers_arr.len()));
83                        }
84                    }
85                }
86
87                Error::config(error_msg)
88            })?;
89            (raw_json, spec)
90        };
91
92        Ok(Self {
93            spec,
94            file_path: path_ref.to_str().map(|s| s.to_string()),
95            raw_document: Some(raw_document),
96        })
97    }
98
99    /// Load OpenAPI spec from string content
100    ///
101    /// Supports both OpenAPI 3.x and Swagger 2.0 specifications.
102    /// Swagger 2.0 specs are automatically converted to OpenAPI 3.0 format.
103    pub fn from_string(content: &str, format: Option<&str>) -> Result<Self> {
104        let raw_json = if format == Some("yaml") || format == Some("yml") {
105            let yaml_value: serde_yaml::Value = serde_yaml::from_str(content)
106                .map_err(|e| Error::config(format!("Failed to parse YAML OpenAPI spec: {}", e)))?;
107            serde_json::to_value(&yaml_value).map_err(|e| {
108                Error::config(format!("Failed to convert YAML OpenAPI spec to JSON: {}", e))
109            })?
110        } else {
111            serde_json::from_str(content)
112                .map_err(|e| Error::config(format!("Failed to parse JSON OpenAPI spec: {}", e)))?
113        };
114
115        // Check if this is a Swagger 2.0 spec and convert if necessary
116        let (raw_document, spec) = if swagger_convert::is_swagger_2(&raw_json) {
117            let converted =
118                swagger_convert::convert_swagger_to_openapi3(&raw_json).map_err(|e| {
119                    Error::config(format!("Failed to convert Swagger 2.0 to OpenAPI 3.0: {}", e))
120                })?;
121            let spec: OpenAPI = serde_json::from_value(converted.clone()).map_err(|e| {
122                Error::config(format!("Failed to parse converted OpenAPI spec: {}", e))
123            })?;
124            (converted, spec)
125        } else {
126            let spec: OpenAPI = serde_json::from_value(raw_json.clone())
127                .map_err(|e| Error::io_with_context("reading OpenAPI spec", e.to_string()))?;
128            (raw_json, spec)
129        };
130
131        Ok(Self {
132            spec,
133            file_path: None,
134            raw_document: Some(raw_document),
135        })
136    }
137
138    /// Load OpenAPI spec from JSON value
139    ///
140    /// Supports both OpenAPI 3.x and Swagger 2.0 specifications.
141    /// Swagger 2.0 specs are automatically converted to OpenAPI 3.0 format.
142    pub fn from_json(json: serde_json::Value) -> Result<Self> {
143        // Check if this is a Swagger 2.0 spec and convert if necessary
144        let (raw_document, spec) = if swagger_convert::is_swagger_2(&json) {
145            let converted = swagger_convert::convert_swagger_to_openapi3(&json).map_err(|e| {
146                Error::config(format!("Failed to convert Swagger 2.0 to OpenAPI 3.0: {}", e))
147            })?;
148            let spec: OpenAPI = serde_json::from_value(converted.clone()).map_err(|e| {
149                Error::config(format!("Failed to parse converted OpenAPI spec: {}", e))
150            })?;
151            (converted, spec)
152        } else {
153            let json_for_doc = json.clone();
154            let spec: OpenAPI = serde_json::from_value(json)
155                .map_err(|e| Error::config(format!("Failed to parse JSON OpenAPI spec: {}", e)))?;
156            (json_for_doc, spec)
157        };
158
159        Ok(Self {
160            spec,
161            file_path: None,
162            raw_document: Some(raw_document),
163        })
164    }
165
166    /// Validate the OpenAPI specification
167    ///
168    /// This method provides basic validation. For comprehensive validation
169    /// with detailed error messages, use `spec_parser::OpenApiValidator::validate()`.
170    pub fn validate(&self) -> Result<()> {
171        // Basic validation - check that we have at least one path
172        if self.spec.paths.paths.is_empty() {
173            return Err(Error::validation("OpenAPI spec must contain at least one path"));
174        }
175
176        // Check that info section has required fields
177        if self.spec.info.title.is_empty() {
178            return Err(Error::validation("OpenAPI spec info must have a title"));
179        }
180
181        if self.spec.info.version.is_empty() {
182            return Err(Error::validation("OpenAPI spec info must have a version"));
183        }
184
185        Ok(())
186    }
187
188    /// Enhanced validation with detailed error reporting
189    pub fn validate_enhanced(&self) -> crate::spec_parser::ValidationResult {
190        // Convert to JSON value for enhanced validator
191        if let Some(raw) = &self.raw_document {
192            let format = if raw.get("swagger").is_some() {
193                crate::spec_parser::SpecFormat::OpenApi20
194            } else if let Some(version) = raw.get("openapi").and_then(|v| v.as_str()) {
195                if version.starts_with("3.1") {
196                    crate::spec_parser::SpecFormat::OpenApi31
197                } else {
198                    crate::spec_parser::SpecFormat::OpenApi30
199                }
200            } else {
201                // Default to 3.0 if we can't determine
202                crate::spec_parser::SpecFormat::OpenApi30
203            };
204            crate::spec_parser::OpenApiValidator::validate(raw, format)
205        } else {
206            // Fallback to basic validation if no raw document
207            crate::spec_parser::ValidationResult::failure(vec![
208                crate::spec_parser::ValidationError::new(
209                    "Cannot perform enhanced validation without raw document".to_string(),
210                ),
211            ])
212        }
213    }
214
215    /// Get the OpenAPI version
216    pub fn version(&self) -> &str {
217        &self.spec.openapi
218    }
219
220    /// Get the API title
221    pub fn title(&self) -> &str {
222        &self.spec.info.title
223    }
224
225    /// Get the API description
226    pub fn description(&self) -> Option<&str> {
227        self.spec.info.description.as_deref()
228    }
229
230    /// Get the API version
231    pub fn api_version(&self) -> &str {
232        &self.spec.info.version
233    }
234
235    /// Get the server URLs
236    pub fn servers(&self) -> &[openapiv3::Server] {
237        &self.spec.servers
238    }
239
240    /// Get all paths defined in the spec
241    pub fn paths(&self) -> &openapiv3::Paths {
242        &self.spec.paths
243    }
244
245    /// Get all schemas defined in the spec
246    pub fn schemas(&self) -> Option<&indexmap::IndexMap<String, ReferenceOr<Schema>>> {
247        self.spec.components.as_ref().map(|c| &c.schemas)
248    }
249
250    /// Get all security schemes defined in the spec
251    pub fn security_schemes(
252        &self,
253    ) -> Option<&indexmap::IndexMap<String, ReferenceOr<openapiv3::SecurityScheme>>> {
254        self.spec.components.as_ref().map(|c| &c.security_schemes)
255    }
256
257    /// Get all operations for a given path
258    pub fn operations_for_path(
259        &self,
260        path: &str,
261    ) -> std::collections::HashMap<String, openapiv3::Operation> {
262        let mut operations = std::collections::HashMap::new();
263
264        if let Some(path_item_ref) = self.spec.paths.paths.get(path) {
265            // Handle the ReferenceOr<PathItem> case
266            if let Some(path_item) = path_item_ref.as_item() {
267                if let Some(op) = &path_item.get {
268                    operations.insert("GET".to_string(), op.clone());
269                }
270                if let Some(op) = &path_item.post {
271                    operations.insert("POST".to_string(), op.clone());
272                }
273                if let Some(op) = &path_item.put {
274                    operations.insert("PUT".to_string(), op.clone());
275                }
276                if let Some(op) = &path_item.delete {
277                    operations.insert("DELETE".to_string(), op.clone());
278                }
279                if let Some(op) = &path_item.patch {
280                    operations.insert("PATCH".to_string(), op.clone());
281                }
282                if let Some(op) = &path_item.head {
283                    operations.insert("HEAD".to_string(), op.clone());
284                }
285                if let Some(op) = &path_item.options {
286                    operations.insert("OPTIONS".to_string(), op.clone());
287                }
288                if let Some(op) = &path_item.trace {
289                    operations.insert("TRACE".to_string(), op.clone());
290                }
291            }
292        }
293
294        operations
295    }
296
297    /// Get all paths with their operations
298    pub fn all_paths_and_operations(
299        &self,
300    ) -> std::collections::HashMap<String, std::collections::HashMap<String, openapiv3::Operation>>
301    {
302        self.spec
303            .paths
304            .paths
305            .iter()
306            .map(|(path, _)| (path.clone(), self.operations_for_path(path)))
307            .collect()
308    }
309
310    /// Get a schema by reference (returns wrapped OpenApiSchema)
311    pub fn get_schema(&self, reference: &str) -> Option<crate::openapi::schema::OpenApiSchema> {
312        self.resolve_schema(reference).map(crate::openapi::schema::OpenApiSchema::new)
313    }
314
315    /// Resolve a schema reference to the raw Schema
316    ///
317    /// This resolves `$ref` references like `#/components/schemas/User` to the
318    /// actual schema definition, handling nested references recursively.
319    pub fn resolve_schema_ref(&self, reference: &str) -> Option<Schema> {
320        self.resolve_schema(reference)
321    }
322
323    /// Validate security requirements
324    pub fn validate_security_requirements(
325        &self,
326        security_requirements: &[openapiv3::SecurityRequirement],
327        auth_header: Option<&str>,
328        api_key: Option<&str>,
329    ) -> Result<()> {
330        if security_requirements.is_empty() {
331            return Ok(());
332        }
333
334        // Security requirements are OR'd - if any requirement is satisfied, pass
335        for requirement in security_requirements {
336            if self.is_security_requirement_satisfied(requirement, auth_header, api_key)? {
337                return Ok(());
338            }
339        }
340
341        Err(Error::validation(
342            "Security validation failed: no valid authentication provided",
343        ))
344    }
345
346    fn resolve_schema(&self, reference: &str) -> Option<Schema> {
347        let mut visited = HashSet::new();
348        self.resolve_schema_recursive(reference, &mut visited)
349    }
350
351    fn resolve_schema_recursive(
352        &self,
353        reference: &str,
354        visited: &mut HashSet<String>,
355    ) -> Option<Schema> {
356        if !visited.insert(reference.to_string()) {
357            tracing::warn!("Detected recursive schema reference: {}", reference);
358            return None;
359        }
360
361        let schema_name = reference.strip_prefix("#/components/schemas/")?;
362        let components = self.spec.components.as_ref()?;
363        let schema_ref = components.schemas.get(schema_name)?;
364
365        match schema_ref {
366            ReferenceOr::Item(schema) => Some(schema.clone()),
367            ReferenceOr::Reference { reference: nested } => {
368                self.resolve_schema_recursive(nested, visited)
369            }
370        }
371    }
372
373    /// Check if a single security requirement is satisfied
374    fn is_security_requirement_satisfied(
375        &self,
376        requirement: &openapiv3::SecurityRequirement,
377        auth_header: Option<&str>,
378        api_key: Option<&str>,
379    ) -> Result<bool> {
380        // All schemes in the requirement must be satisfied (AND)
381        for (scheme_name, _scopes) in requirement {
382            if !self.is_security_scheme_satisfied(scheme_name, auth_header, api_key)? {
383                return Ok(false);
384            }
385        }
386        Ok(true)
387    }
388
389    /// Check if a security scheme is satisfied
390    fn is_security_scheme_satisfied(
391        &self,
392        scheme_name: &str,
393        auth_header: Option<&str>,
394        api_key: Option<&str>,
395    ) -> Result<bool> {
396        let security_schemes = match self.security_schemes() {
397            Some(schemes) => schemes,
398            None => return Ok(false),
399        };
400
401        let scheme = match security_schemes.get(scheme_name) {
402            Some(scheme) => scheme,
403            None => {
404                return Err(Error::config(format!("Security scheme '{}' not found", scheme_name)))
405            }
406        };
407
408        let scheme = match scheme {
409            ReferenceOr::Item(s) => s,
410            ReferenceOr::Reference { reference } => {
411                // Resolve $ref like "#/components/securitySchemes/BearerAuth"
412                let ref_name =
413                    reference.strip_prefix("#/components/securitySchemes/").ok_or_else(|| {
414                        Error::config(format!(
415                            "Unsupported security scheme reference format: {}",
416                            reference
417                        ))
418                    })?;
419                match security_schemes.get(ref_name) {
420                    Some(ReferenceOr::Item(resolved)) => resolved,
421                    Some(ReferenceOr::Reference { .. }) => {
422                        return Err(Error::config(format!(
423                            "Nested security scheme reference not supported: {}",
424                            ref_name
425                        )))
426                    }
427                    None => {
428                        return Err(Error::config(format!(
429                            "Security scheme '{}' not found",
430                            ref_name
431                        )))
432                    }
433                }
434            }
435        };
436
437        match scheme {
438            openapiv3::SecurityScheme::HTTP { scheme, .. } => {
439                match scheme.as_str() {
440                    "bearer" => match auth_header {
441                        Some(header) if header.starts_with("Bearer ") => Ok(true),
442                        _ => Ok(false),
443                    },
444                    "basic" => match auth_header {
445                        Some(header) if header.starts_with("Basic ") => Ok(true),
446                        _ => Ok(false),
447                    },
448                    _ => Ok(false), // Unsupported scheme
449                }
450            }
451            openapiv3::SecurityScheme::APIKey { location, .. } => match location {
452                openapiv3::APIKeyLocation::Header => Ok(auth_header.is_some()),
453                openapiv3::APIKeyLocation::Query => Ok(api_key.is_some()),
454                openapiv3::APIKeyLocation::Cookie => Ok(api_key.is_some()),
455            },
456            openapiv3::SecurityScheme::OpenIDConnect { .. } => {
457                // OpenID Connect uses Bearer tokens, same as OAuth2
458                match auth_header {
459                    Some(header) if header.starts_with("Bearer ") => Ok(true),
460                    _ => Ok(false),
461                }
462            }
463            openapiv3::SecurityScheme::OAuth2 { .. } => {
464                // For OAuth2, check if Bearer token is provided
465                match auth_header {
466                    Some(header) if header.starts_with("Bearer ") => Ok(true),
467                    _ => Ok(false),
468                }
469            }
470        }
471    }
472
473    /// Get global security requirements
474    pub fn get_global_security_requirements(&self) -> Vec<openapiv3::SecurityRequirement> {
475        self.spec.security.clone().unwrap_or_default()
476    }
477
478    /// Resolve a request body reference
479    pub fn get_request_body(&self, reference: &str) -> Option<&openapiv3::RequestBody> {
480        if let Some(components) = &self.spec.components {
481            if let Some(param_name) = reference.strip_prefix("#/components/requestBodies/") {
482                if let Some(request_body_ref) = components.request_bodies.get(param_name) {
483                    return request_body_ref.as_item();
484                }
485            }
486        }
487        None
488    }
489
490    /// Resolve a response reference
491    pub fn get_response(&self, reference: &str) -> Option<&openapiv3::Response> {
492        if let Some(components) = &self.spec.components {
493            if let Some(response_name) = reference.strip_prefix("#/components/responses/") {
494                if let Some(response_ref) = components.responses.get(response_name) {
495                    return response_ref.as_item();
496                }
497            }
498        }
499        None
500    }
501
502    /// Resolve an example reference
503    pub fn get_example(&self, reference: &str) -> Option<&openapiv3::Example> {
504        if let Some(components) = &self.spec.components {
505            if let Some(example_name) = reference.strip_prefix("#/components/examples/") {
506                if let Some(example_ref) = components.examples.get(example_name) {
507                    return example_ref.as_item();
508                }
509            }
510        }
511        None
512    }
513}
514
515#[cfg(test)]
516mod tests {
517    use super::*;
518    use openapiv3::{SchemaKind, Type};
519
520    #[test]
521    fn resolves_security_scheme_ref() {
522        let yaml = r#"
523openapi: 3.0.3
524info:
525  title: Test API
526  version: "1.0.0"
527paths:
528  /test:
529    get:
530      security:
531        - BearerRef: []
532      responses:
533        '200':
534          description: OK
535components:
536  securitySchemes:
537    BearerAuth:
538      type: http
539      scheme: bearer
540    BearerRef:
541      $ref: '#/components/securitySchemes/BearerAuth'
542        "#;
543
544        let spec = OpenApiSpec::from_string(yaml, Some("yaml")).expect("spec parses");
545
546        // Bearer token should satisfy the referenced scheme
547        let result = spec
548            .is_security_scheme_satisfied("BearerRef", Some("Bearer token123"), None)
549            .expect("should resolve ref");
550        assert!(result);
551
552        // Missing token should fail
553        let result = spec
554            .is_security_scheme_satisfied("BearerRef", None, None)
555            .expect("should resolve ref");
556        assert!(!result);
557    }
558
559    #[test]
560    fn resolves_nested_schema_references() {
561        let yaml = r#"
562openapi: 3.0.3
563info:
564  title: Test API
565  version: "1.0.0"
566paths: {}
567components:
568  schemas:
569    Apiary:
570      type: object
571      properties:
572        id:
573          type: string
574        hive:
575          $ref: '#/components/schemas/Hive'
576    Hive:
577      type: object
578      properties:
579        name:
580          type: string
581    HiveWrapper:
582      $ref: '#/components/schemas/Hive'
583        "#;
584
585        let spec = OpenApiSpec::from_string(yaml, Some("yaml")).expect("spec parses");
586
587        let apiary = spec.get_schema("#/components/schemas/Apiary").expect("resolve apiary schema");
588        assert!(matches!(apiary.schema.schema_kind, SchemaKind::Type(Type::Object(_))));
589
590        let wrapper = spec
591            .get_schema("#/components/schemas/HiveWrapper")
592            .expect("resolve wrapper schema");
593        assert!(matches!(wrapper.schema.schema_kind, SchemaKind::Type(Type::Object(_))));
594    }
595}
mockforge_core/openapi/spec.rs

mockforge_core/openapi/
spec.rs
