Repository: wafflespeanut/paperclip
Pull request #297 (2021-02-11 15:00:45)

fix(doc): missing documentation on types
Add missing documentation to struct definitions.
Updated tests.

Resolves  #290

tiagolobocastro: Mind having a look at this @dunnock? Thanks

Btw also noticed that Body type parameters don't have a description (it's set to None). Should they?

Patch:
diff --git a/macros/src/actix.rs b/macros/src/actix.rs
index e580c301..1b47d414 100644
--- a/macros/src/actix.rs
+++ b/macros/src/actix.rs
@@ -491,7 +491,9 @@ pub fn emit_v2_definition(input: TokenStream) -> TokenStream {
                 schema.data_type = Some(DataType::Object);
             ));
             match &s.fields {
-                Fields::Named(ref f) => handle_field_struct(f, &props, &mut props_gen),
+                Fields::Named(ref f) => {
+                    handle_field_struct(f, &item_ast.attrs, &props, &mut props_gen)
+                }
                 Fields::Unnamed(ref f) => {
                     handle_unnamed_field_struct(f, &item_ast.attrs, &mut props_gen)
                 }
@@ -895,9 +897,18 @@ fn check_empty_schema(item_ast: &DeriveInput) -> Option<TokenStream> {
 /// Generates code for a struct with fields.
 fn handle_field_struct(
     fields: &FieldsNamed,
+    struct_attr: &[Attribute],
     serde: &SerdeProps,
     props_gen: &mut proc_macro2::TokenStream,
 ) {
+    let docs = extract_documentation(struct_attr);
+    let docs = docs.trim();
+
+    props_gen.extend(quote!({
+        if !#docs.is_empty() {
+            schema.description = Some(#docs.to_string());
+        }
+    }));
     for field in &fields.named {
         let mut field_name = field
             .ident


Test patch:
diff --git a/tests/test_app.rs b/tests/test_app.rs
index 1891a771..ea1f2722 100644
--- a/tests/test_app.rs
+++ b/tests/test_app.rs
@@ -150,6 +150,7 @@ fn test_simple_app() {
                   "info":{"title":"","version":""},
                   "definitions": {
                     "Pet": {
+                      "description":"Pets are awesome!",
                       "properties": {
                         "class": {
                           "enum": ["dog", "cat", "other"],
@@ -1236,6 +1237,7 @@ fn test_serde_flatten() {
                 json!({
                     "definitions": {
                         "Images": {
+                          "description": "Images response with paging information embedded",
                           "properties": {
                             "data": {
                               "items": {
@@ -2405,6 +2407,7 @@ fn test_errors_app() {
                   "info":{"title":"","version":""},
                   "definitions": {
                     "Pet": {
+                      "description": "Pets are awesome!",
                       "properties": {
                         "class": {
                           "enum": ["dog", "cat", "other"],
@@ -2567,6 +2570,7 @@ fn test_security_app() {
                   "info":{"title":"","version":""},
                   "definitions": {
                     "Pet": {
+                      "description": "Pets are awesome!",
                       "properties": {
                         "class": {
                           "enum": ["dog", "cat", "other"],