Description of complex object parameters

[adabbas]

Hello,

I have a GET request which is as follows :

@GetMapping("/search")
  public ResponseEntity<List<User>> findUsers(@ParameterObject UserCriteria criteria) {
    log.debug("REST request to search users by criteria: {}", criteria);
    return ResponseEntity.ok().body(userService.findAllByCriteria(criteria));
  }

The UserCriteria parameter object is a class which looks like this :

public class UserCriteria {

  @Schema(description = "First name of the user")
  private StringFilter firstName;

  @Schema(description = "Last name of the user")
  private StringFilter lastName;
}

The UserCriteria class has two fields which are not primitive types. They refer to a StringFilter class, which looks like this :

public class StringFilter extends Filter<String> {

  @Schema(description = "Contains query")
    private String contains;
  @Schema(description = "Does not contain query")
    private String doesNotContain;

}

But when I request this API documentation (by sending /v3/api-docs request), this is what I get (for the "Schemas" part) :

"components": {
        "schemas": {
             "StringFilter": {
                "type": "object",
                "properties": {
                    "contains": {
                        "type": "string",
                        "description": "Contains query"
                    },
                    "doesNotContain": {
                        "type": "string",
                        "description": "Does not contain query"
                    },
                },
                "description": "Last name of the user"
            },
            "UserCriteria": {
                "type": "object",
                "properties": {
                    "firstName": {
                        "$ref": "#/components/schemas/StringFilter"
                    },
                    "lastName": {
                        "$ref": "#/components/schemas/StringFilter"
                    }
                }
            },
        }
   }

I see that Usercriteria's lastName property description is written as StringFilter's schema description. And that firstName and lastName properties descriptions are left empty.
Is this normal ? I mean, I excpected something like this :

"components": {
        "schemas": {
             "StringFilter": {
                "type": "object",
                "properties": {
                    "contains": {
                        "type": "string",
                        "description": "Contains query"
                    },
                    "doesNotContain": {
                        "type": "string",
                        "description": "Does not contain query"
                    },
                },
            },
            "UserCriteria": {
                "type": "object",
                "properties": {
                    "firstName": {
                        "$ref": "#/components/schemas/StringFilter",
                        "description": "First name of the user"
                    },
                    "lastName": {
                        "$ref": "#/components/schemas/StringFilter",
                        "description": "Last name of the user"
                    }
                }
            },
        }
   }

Am I correct to expect this ? If not, or if this issue has already been opened, please accept my apologies.

Thank you for your time and congratulations on this great project !

[bnasslahsen]

Using swagger-core library, the complex (objects) payloads are always resolved as a reference to a schema defined in components.
If you need two different descriptions for the same complex object, you should declare two different schemas explicitly, each one with it's own description.

Your question is a duplicate of #1152, #817 or #685 or #782, or #685.

I will add a generic answer on the F.A.Q, which might be more useful.

[adabbas]

Thank you very much ! 😄