openapi_deref/

resolved.rs

use serde_json::Value;

use crate::error::{PartialResolveError, RefError};

/// Result of resolving all `$ref` pointers in a JSON document.
///
/// Contains the resolved document alongside any non-fatal ref errors.
///
/// # Checking results
///
/// - [`is_complete()`](Self::is_complete) — `true` when zero errors
/// - [`into_value()`](Self::into_value) — strict conversion to `Result<Value, _>`
///
/// # Convenience iterators
///
/// Inspect specific error categories **without** importing [`RefError`]:
///
/// - [`cycles()`](Self::cycles) — circular `$ref` strings
/// - [`missing_refs()`](Self::missing_refs) — not-found `$ref` strings
/// - [`external_refs()`](Self::external_refs) — unsupported external URI strings
/// - [`sibling_keys_ignored()`](Self::sibling_keys_ignored) — sibling keys dropped (non-object target)
#[derive(Debug, Clone)]
pub struct ResolvedDoc {
    /// The document with all resolvable `$ref` pointers expanded inline.
    /// Unresolvable refs are preserved as raw `{"$ref": "..."}` objects.
    pub value: Value,
    /// Non-fatal ref errors encountered during resolution.
    pub ref_errors: Vec<RefError>,
}

impl ResolvedDoc {
    /// Returns `true` if all `$ref` pointers were successfully resolved.
    pub fn is_complete(&self) -> bool {
        self.ref_errors.is_empty()
    }

    /// Converts into the resolved [`Value`] if no ref errors were encountered.
    ///
    /// On failure, the returned [`PartialResolveError`] still provides access
    /// to the partially-resolved document via its `value` field.
    ///
    /// # Example
    ///
    /// ```
    /// # use serde_json::json;
    /// # use openapi_deref::resolve;
    /// let spec = json!({
    ///     "components": { "schemas": { "X": { "type": "string" } } },
    ///     "f": { "$ref": "#/components/schemas/X" }
    /// });
    /// let value = resolve(&spec).unwrap().into_value().unwrap();
    /// assert_eq!(value["f"]["type"], "string");
    /// ```
    pub fn into_value(self) -> Result<Value, PartialResolveError> {
        if self.ref_errors.is_empty() {
            Ok(self.value)
        } else {
            Err(PartialResolveError {
                value: self.value,
                ref_errors: self.ref_errors,
            })
        }
    }

    /// Iterates over `$ref` strings that form circular references.
    ///
    /// # Example
    ///
    /// ```
    /// # use serde_json::json;
    /// # use openapi_deref::resolve;
    /// let spec = json!({
    ///     "components": { "schemas": {
    ///         "Node": { "properties": { "child": { "$ref": "#/components/schemas/Node" } } }
    ///     }},
    ///     "root": { "$ref": "#/components/schemas/Node" }
    /// });
    /// let doc = resolve(&spec).unwrap();
    /// let cycles: Vec<&str> = doc.cycles().collect();
    /// assert_eq!(cycles, ["#/components/schemas/Node"]);
    /// ```
    pub fn cycles(&self) -> impl Iterator<Item = &str> + '_ {
        self.ref_errors.iter().filter_map(|e| match e {
            RefError::Cycle { ref_str } => Some(ref_str.as_str()),
            _ => None,
        })
    }

    /// Iterates over external `$ref` strings (unsupported by this resolver).
    ///
    /// # Example
    ///
    /// ```
    /// # use serde_json::json;
    /// # use openapi_deref::resolve;
    /// let spec = json!({ "ext": { "$ref": "https://example.com/schema.json" } });
    /// let doc = resolve(&spec).unwrap();
    /// assert_eq!(doc.external_refs().next(), Some("https://example.com/schema.json"));
    /// ```
    pub fn external_refs(&self) -> impl Iterator<Item = &str> + '_ {
        self.ref_errors.iter().filter_map(|e| match e {
            RefError::External { ref_str } => Some(ref_str.as_str()),
            _ => None,
        })
    }

    /// Iterates over `$ref` strings where sibling keys were dropped because
    /// the resolved target was not a JSON object.
    ///
    /// # Example
    ///
    /// ```
    /// # use serde_json::json;
    /// # use openapi_deref::resolve;
    /// let spec = json!({
    ///     "definitions": { "val": 42 },
    ///     "target": { "$ref": "#/definitions/val", "description": "dropped" }
    /// });
    /// let doc = resolve(&spec).unwrap();
    /// assert_eq!(doc.sibling_keys_ignored().next(), Some("#/definitions/val"));
    /// ```
    pub fn sibling_keys_ignored(&self) -> impl Iterator<Item = &str> + '_ {
        self.ref_errors.iter().filter_map(|e| match e {
            RefError::SiblingKeysIgnored { ref_str } => Some(ref_str.as_str()),
            _ => None,
        })
    }

    /// Iterates over `$ref` strings whose targets were not found.
    ///
    /// # Example
    ///
    /// ```
    /// # use serde_json::json;
    /// # use openapi_deref::resolve;
    /// let spec = json!({ "broken": { "$ref": "#/does/not/exist" } });
    /// let doc = resolve(&spec).unwrap();
    /// assert_eq!(doc.missing_refs().next(), Some("#/does/not/exist"));
    /// ```
    pub fn missing_refs(&self) -> impl Iterator<Item = &str> + '_ {
        self.ref_errors.iter().filter_map(|e| match e {
            RefError::TargetNotFound { ref_str } => Some(ref_str.as_str()),
            _ => None,
        })
    }
}

#[cfg(test)]
mod tests {
    use serde_json::json;

    use crate::resolve;

    #[test]
    fn into_value_ok_on_complete_resolution() {
        let spec = json!({
            "components": { "schemas": { "Id": { "type": "integer" } } },
            "field": { "$ref": "#/components/schemas/Id" }
        });
        let value = resolve(&spec).unwrap().into_value().unwrap();
        assert_eq!(value["field"]["type"], "integer");
    }

    #[test]
    fn into_value_err_preserves_partial_value() {
        let spec = json!({
            "schema": { "$ref": "#/missing" }
        });
        let err = resolve(&spec).unwrap().into_value().unwrap_err();

        assert_eq!(err.ref_errors.len(), 1);
        assert_eq!(err.value["schema"]["$ref"], "#/missing");
    }

    #[test]
    fn resolved_doc_cycles_iterator() {
        let spec = json!({
            "components": {
                "schemas": {
                    "Node": {
                        "type": "object",
                        "properties": { "child": { "$ref": "#/components/schemas/Node" } }
                    }
                }
            },
            "root": { "$ref": "#/components/schemas/Node" }
        });
        let doc = resolve(&spec).unwrap();

        let cycles: Vec<&str> = doc.cycles().collect();
        assert_eq!(cycles, ["#/components/schemas/Node"]);
        assert_eq!(doc.missing_refs().count(), 0);
        assert_eq!(doc.external_refs().count(), 0);
    }

    #[test]
    fn resolved_doc_missing_refs_iterator() {
        let spec = json!({
            "a": { "$ref": "#/missing_a" },
            "b": { "$ref": "#/missing_b" }
        });
        let doc = resolve(&spec).unwrap();

        let missing: Vec<&str> = doc.missing_refs().collect();
        assert_eq!(missing.len(), 2);
        assert!(missing.contains(&"#/missing_a"));
        assert!(missing.contains(&"#/missing_b"));
        assert_eq!(doc.cycles().count(), 0);
    }

    #[test]
    fn resolved_doc_sibling_keys_ignored_iterator() {
        let spec = json!({
            "definitions": { "val": 42 },
            "a": { "$ref": "#/definitions/val", "desc": "dropped" }
        });
        let doc = resolve(&spec).unwrap();

        let ignored: Vec<&str> = doc.sibling_keys_ignored().collect();
        assert_eq!(ignored, ["#/definitions/val"]);
        assert_eq!(doc.cycles().count(), 0);
        assert_eq!(doc.missing_refs().count(), 0);
    }

    #[test]
    fn resolved_doc_external_refs_iterator() {
        let spec = json!({
            "a": { "$ref": "https://example.com/a.json" },
            "b": { "$ref": "./local.json#/foo" }
        });
        let doc = resolve(&spec).unwrap();

        let external: Vec<&str> = doc.external_refs().collect();
        assert_eq!(external.len(), 2);
        assert!(external.contains(&"https://example.com/a.json"));
        assert!(external.contains(&"./local.json#/foo"));
    }
}