fix(openapi): unwrap boxed schema refs and strip embedded JSON-schema docs

reflectapi-demo/src/tests/mod.rs

@@ -38,6 +38,107 @@ fn write_openapi_spec() {
     insta::assert_snapshot!(s);
 }
 
+#[test]
+fn generated_openapi_spec_has_resolvable_refs() {
+    let (schema, _) = crate::builder().build().unwrap();
+
+    let s = reflectapi::codegen::openapi::generate(
+        &schema,
+        reflectapi::codegen::openapi::Config::default()
+            .exclude_tags(BTreeSet::from_iter(["internal".to_string()])),
+    )
+    .unwrap();
+    let spec: serde_json::Value = serde_json::from_str(&s).unwrap();
+
+    assert_no_embedded_json_schema_docs(&spec, "$".to_owned());
+    assert_local_openapi_refs_resolve(&spec);
+}
+
+fn assert_local_openapi_refs_resolve(spec: &serde_json::Value) {
+    let schemas = spec
+        .pointer("/components/schemas")
+        .and_then(serde_json::Value::as_object)
+        .expect("OpenAPI spec should have components.schemas");
+
+    let mut unresolved_refs = Vec::new();
+    collect_unresolved_local_refs(spec, schemas, "$".to_owned(), &mut unresolved_refs);
+
+    assert!(
+        unresolved_refs.is_empty(),
+        "OpenAPI spec contains unresolved local refs:\n{}",
+        unresolved_refs.join("\n")
+    );
+}
+
+fn collect_unresolved_local_refs(
+    value: &serde_json::Value,
+    schemas: &serde_json::Map<String, serde_json::Value>,
+    path: String,
+    unresolved_refs: &mut Vec<String>,
+) {
+    match value {
+        serde_json::Value::Object(object) => {
+            if let Some(ref_path) = object.get("$ref").and_then(serde_json::Value::as_str) {
+                if let Some(component_name) = ref_path.strip_prefix("#/components/schemas/") {
+                    if !schemas.contains_key(component_name) {
+                        unresolved_refs.push(format!("{path}: {ref_path}"));
+                    }
+                } else if ref_path.starts_with('#') {
+                    unresolved_refs.push(format!("{path}: unsupported local ref {ref_path}"));
+                }
+            }
+
+            for (key, child) in object {
+                collect_unresolved_local_refs(
+                    child,
+                    schemas,
+                    format!("{path}.{}", key.replace('.', "\\.")),
+                    unresolved_refs,
+                );
+            }
+        }
+        serde_json::Value::Array(items) => {
+            for (index, child) in items.iter().enumerate() {
+                collect_unresolved_local_refs(
+                    child,
+                    schemas,
+                    format!("{path}[{index}]"),
+                    unresolved_refs,
+                );
+            }
+        }
+        serde_json::Value::Null
+        | serde_json::Value::Bool(_)
+        | serde_json::Value::Number(_)
+        | serde_json::Value::String(_) => {}
+    }
+}
+
+fn assert_no_embedded_json_schema_docs(value: &serde_json::Value, path: String) {
+    match value {
+        serde_json::Value::String(text) => {
+            assert!(
+                !text.contains("<summary>JSON schema</summary>"),
+                "OpenAPI spec contains embedded JSON schema docs at {path}"
+            );
+        }
+        serde_json::Value::Object(object) => {
+            for (key, child) in object {
+                assert_no_embedded_json_schema_docs(
+                    child,
+                    format!("{path}.{}", key.replace('.', "\\.")),
+                );
+            }
+        }
+        serde_json::Value::Array(items) => {
+            for (index, child) in items.iter().enumerate() {
+                assert_no_embedded_json_schema_docs(child, format!("{path}[{index}]"));
+            }
+        }
+        serde_json::Value::Null | serde_json::Value::Bool(_) | serde_json::Value::Number(_) => {}
+    }
+}
+
 #[test]
 fn write_rust_client() {
     let (schema, _) = crate::builder().build().unwrap();

reflectapi-demo/src/tests/serde.rs

@@ -1077,6 +1077,20 @@ fn test_box_field_unwrapping() {
     assert_snapshot!(TreeNode);
 }
 
+#[test]
+fn test_box_root_openapi_unwrapping() {
+    #[derive(
+        serde::Serialize, serde::Deserialize, Debug, reflectapi::Input, reflectapi::Output,
+    )]
+    struct TreeNode {
+        label: String,
+        child: Option<Box<TreeNode>>,
+    }
+
+    let schema = super::into_schema::<Box<TreeNode>>();
+    insta::assert_json_snapshot!(reflectapi::codegen::openapi::Spec::from(&schema));
+}
+
 #[test]
 fn test_nested_generic_containers() {
     #[derive(