Support description

Author: owjs3901

.changepacks/changepack_log_1DpbP4f1cc9lsoConhMuB.json

@@ -0,0 +1 @@
+{"changes":{"crates/vespera_macro/Cargo.toml":"Patch","crates/vespera/Cargo.toml":"Patch","crates/vespera_core/Cargo.toml":"Patch"},"note":"Support description","date":"2026-02-03T18:15:43.339445900Z"}

Cargo.lock

@@ -74,7 +74,7 @@ pub enum StringFormat {
 }
 
 /// JSON Schema definition
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Schema {
     /// Schema reference ($ref) - if present, other fields are ignored

crates/vespera_core/src/schema.rs

@@ -3,6 +3,33 @@ use std::collections::{BTreeMap, HashMap};
 use syn::{Fields, Type};
 use vespera_core::schema::{Reference, Schema, SchemaRef, SchemaType};
 
+/// Extract doc comments from attributes.
+/// Returns concatenated doc comment string or None if no doc comments.
+pub fn extract_doc_comment(attrs: &[syn::Attribute]) -> Option<String> {
+    let mut doc_lines = Vec::new();
+
+    for attr in attrs {
+        if attr.path().is_ident("doc")
+            && let syn::Meta::NameValue(meta_nv) = &attr.meta
+            && let syn::Expr::Lit(syn::ExprLit {
+                lit: syn::Lit::Str(lit_str),
+                ..
+            }) = &meta_nv.value
+        {
+            let line = lit_str.value();
+            // Trim leading space that rustdoc adds
+            let trimmed = line.strip_prefix(' ').unwrap_or(&line);
+            doc_lines.push(trimmed.to_string());
+        }
+    }
+
+    if doc_lines.is_empty() {
+        None
+    } else {
+        Some(doc_lines.join("\n"))
+    }
+}
+
 /// Strips the `r#` prefix from raw identifiers.
 /// E.g., `r#type` becomes `type`.
 pub fn strip_raw_prefix(ident: &str) -> &str {
@@ -437,6 +464,9 @@ pub fn parse_enum_to_schema(
     known_schemas: &HashMap<String, String>,
     struct_definitions: &HashMap<String, String>,
 ) -> Schema {
+    // Extract enum-level doc comment for schema description
+    let enum_description = extract_doc_comment(&enum_item.attrs);
+
     // Extract rename_all attribute from enum
     let rename_all = extract_rename_all(&enum_item.attrs);
 
@@ -466,6 +496,7 @@ pub fn parse_enum_to_schema(
 
         Schema {
             schema_type: Some(SchemaType::String),
+            description: enum_description,
             r#enum: if enum_values.is_empty() {
                 None
             } else {
@@ -488,10 +519,14 @@ pub fn parse_enum_to_schema(
                 rename_field(&variant_name, rename_all.as_deref())
             };
 
+            // Extract variant-level doc comment
+            let variant_description = extract_doc_comment(&variant.attrs);
+
             let variant_schema = match &variant.fields {
                 syn::Fields::Unit => {
                     // Unit variant: {"const": "VariantName"}
                     Schema {
+                        description: variant_description,
                         r#enum: Some(vec![serde_json::Value::String(variant_key)]),
                         ..Schema::string()
                     }
@@ -510,6 +545,7 @@ pub fn parse_enum_to_schema(
                         properties.insert(variant_key.clone(), inner_schema);
 
                         Schema {
+                            description: variant_description.clone(),
                             properties: Some(properties),
                             required: Some(vec![variant_key]),
                             ..Schema::object()
@@ -546,6 +582,7 @@ pub fn parse_enum_to_schema(
                         );
 
                         Schema {
+                            description: variant_description.clone(),
                             properties: Some(properties),
                             required: Some(vec![variant_key]),
                             ..Schema::object()
@@ -577,9 +614,31 @@ pub fn parse_enum_to_schema(
                         };
 
                         let field_type = &field.ty;
-                        let schema_ref =
+                        let mut schema_ref =
                             parse_type_to_schema_ref(field_type, known_schemas, struct_definitions);
 
+                        // Extract doc comment from field and set as description
+                        if let Some(doc) = extract_doc_comment(&field.attrs) {
+                            match &mut schema_ref {
+                                SchemaRef::Inline(schema) => {
+                                    schema.description = Some(doc);
+                                }
+                                SchemaRef::Ref(_) => {
+                                    let ref_schema = std::mem::replace(
+                                        &mut schema_ref,
+                                        SchemaRef::Inline(Box::new(Schema::object())),
+                                    );
+                                    if let SchemaRef::Ref(reference) = ref_schema {
+                                        schema_ref = SchemaRef::Inline(Box::new(Schema {
+                                            description: Some(doc),
+                                            all_of: Some(vec![SchemaRef::Ref(reference)]),
+                                            ..Default::default()
+                                        }));
+                                    }
+                                }
+                            }
+                        }
+
                         variant_properties.insert(field_name.clone(), schema_ref);
 
                         // Check if field is Option<T>
@@ -621,6 +680,7 @@ pub fn parse_enum_to_schema(
                     );
 
                     Schema {
+                        description: variant_description,
                         properties: Some(properties),
                         required: Some(vec![variant_key]),
                         ..Schema::object()
@@ -633,6 +693,7 @@ pub fn parse_enum_to_schema(
 
         Schema {
             schema_type: None, // oneOf doesn't have a single type
+            description: enum_description,
             one_of: if one_of_schemas.is_empty() {
                 None
             } else {
@@ -651,6 +712,9 @@ pub fn parse_struct_to_schema(
     let mut properties = BTreeMap::new();
     let mut required = Vec::new();
 
+    // Extract struct-level doc comment for schema description
+    let struct_description = extract_doc_comment(&struct_item.attrs);
+
     // Extract rename_all attribute from struct
     let rename_all = extract_rename_all(&struct_item.attrs);
 
@@ -681,6 +745,31 @@ pub fn parse_struct_to_schema(
                 let mut schema_ref =
                     parse_type_to_schema_ref(field_type, known_schemas, struct_definitions);
 
+                // Extract doc comment from field and set as description
+                if let Some(doc) = extract_doc_comment(&field.attrs) {
+                    match &mut schema_ref {
+                        SchemaRef::Inline(schema) => {
+                            schema.description = Some(doc);
+                        }
+                        SchemaRef::Ref(_) => {
+                            // For $ref schemas, we need to wrap in an allOf to add description
+                            // OpenAPI 3.1 allows siblings to $ref, so we can add description directly
+                            // by converting to inline schema with description + allOf[$ref]
+                            let ref_schema = std::mem::replace(
+                                &mut schema_ref,
+                                SchemaRef::Inline(Box::new(Schema::object())),
+                            );
+                            if let SchemaRef::Ref(reference) = ref_schema {
+                                schema_ref = SchemaRef::Inline(Box::new(Schema {
+                                    description: Some(doc),
+                                    all_of: Some(vec![SchemaRef::Ref(reference)]),
+                                    ..Default::default()
+                                }));
+                            }
+                        }
+                    }
+                }
+
                 // Check for default attribute
                 let has_default = extract_default(&field.attrs).is_some();
 
@@ -727,6 +816,7 @@ pub fn parse_struct_to_schema(
 
     Schema {
         schema_type: Some(SchemaType::Object),
+        description: struct_description,
         properties: if properties.is_empty() {
             None
         } else {

crates/vespera_macro/src/parser/schema.rs

@@ -1396,19 +1396,19 @@ fn generate_inline_relation_type(
                 continue;
             }
 
-            // Keep only serde attributes
-            let serde_attrs: Vec<syn::Attribute> = field
+            // Keep serde and doc attributes
+            let kept_attrs: Vec<syn::Attribute> = field
                 .attrs
                 .iter()
-                .filter(|attr| attr.path().is_ident("serde"))
+                .filter(|attr| attr.path().is_ident("serde") || attr.path().is_ident("doc"))
                 .cloned()
                 .collect();
 
             let field_ty = &field.ty;
             fields.push(InlineField {
                 name: field_ident.clone(),
                 ty: quote::quote!(#field_ty),
-                attrs: serde_attrs,
+                attrs: kept_attrs,
             });
         }
     }
@@ -1472,19 +1472,19 @@ fn generate_inline_relation_type_no_relations(
                 continue;
             }
 
-            // Keep only serde attributes
-            let serde_attrs: Vec<syn::Attribute> = field
+            // Keep serde and doc attributes
+            let kept_attrs: Vec<syn::Attribute> = field
                 .attrs
                 .iter()
-                .filter(|attr| attr.path().is_ident("serde"))
+                .filter(|attr| attr.path().is_ident("serde") || attr.path().is_ident("doc"))
                 .cloned()
                 .collect();
 
             let field_ty = &field.ty;
             fields.push(InlineField {
                 name: field_ident.clone(),
                 ty: quote::quote!(#field_ty),
-                attrs: serde_attrs,
+                attrs: kept_attrs,
             });
         }
     }
@@ -2683,6 +2683,13 @@ pub fn generate_schema_type_code(
         })
         .collect();
 
+    // Extract doc comments from source struct to carry over to generated struct
+    let struct_doc_attrs: Vec<_> = parsed_struct
+        .attrs
+        .iter()
+        .filter(|attr| attr.path().is_ident("doc"))
+        .collect();
+
     // Determine the rename_all strategy:
     // 1. If input.rename_all is specified, use it
     // 2. Else if source has rename_all, use it
@@ -2838,7 +2845,7 @@ pub fn generate_schema_type_code(
             let vis = &field.vis;
             let source_field_ident = field.ident.clone().unwrap();
 
-            // Filter field attributes: only keep serde attributes, remove sea_orm and others
+            // Filter field attributes: keep serde and doc attributes, remove sea_orm and others
             // This is important when using schema_type! with models from other files
             // that may have ORM-specific attributes we don't want in the generated struct
             let serde_field_attrs: Vec<_> = field
@@ -2847,6 +2854,13 @@ pub fn generate_schema_type_code(
                 .filter(|attr| attr.path().is_ident("serde"))
                 .collect();
 
+            // Extract doc attributes to carry over comments to the generated struct
+            let doc_attrs: Vec<_> = field
+                .attrs
+                .iter()
+                .filter(|attr| attr.path().is_ident("doc"))
+                .collect();
+
             // Check if field should be renamed
             if let Some(new_name) = rename_map.get(&rust_field_name) {
                 // Create new identifier for the field
@@ -2874,6 +2888,7 @@ pub fn generate_schema_type_code(
                     extract_field_rename(&field.attrs).unwrap_or_else(|| rust_field_name.clone());
 
                 field_tokens.push(quote! {
+                    #(#doc_attrs)*
                     #(#filtered_attrs)*
                     #[serde(rename = #json_name)]
                     #vis #new_field_ident: #field_ty
@@ -2887,10 +2902,11 @@ pub fn generate_schema_type_code(
                     is_relation,
                 ));
             } else {
-                // No rename, keep field with only serde attrs
+                // No rename, keep field with serde and doc attrs
                 let field_ident = field.ident.clone().unwrap();
 
                 field_tokens.push(quote! {
+                    #(#doc_attrs)*
                     #(#serde_field_attrs)*
                     #vis #field_ident: #field_ty
                 });
@@ -2989,6 +3005,7 @@ pub fn generate_schema_type_code(
         // Inline types for circular relation references
         #(#inline_type_definitions)*
 
+        #(#struct_doc_attrs)*
         #[derive(serde::Serialize, serde::Deserialize, #clone_derive #schema_derive)]
         #schema_name_attr
         #[serde(rename_all = #effective_rename_all)]