Swagger-core: Add annotation @ApiImplicitModel support

[john24318]

For more easy to use @ApiImplicitParams purpose, I hope swagger will support the annotation which I describe an example below.

@ApiImplicitModel(derived=User.class, properties={"id", "username", "password" ,"nickname", "contact.address", "contact.phone", "contact.email"})

The request/response model will show in UI:
type : object
{
id: 0
username: "",
password: "",
nickname: "",
contact: {
address: "",
phone: "",
email: ""
}
}

Put @ApiImplicitModel on method or parameter target.
The properties must be the property names of derived type.

Sincerely.

[fehguy]

Hi, it's not entirely clear what you're looking to do. Can you please elaborate on your use case?

[john24318]

In many situations, I hope a request/response model will display suitable properties but not all properties for some APIs. For example, my User model can be used to create users or to update users.

In my create API, it has a parameter with User type. I hope Swagger will hide the "id" property in the User model because it is generated by the database. So I can put an annotation @ApiImplicitModel(derived=User.class, properties={"username", "password" ,"nickname", "contact.address", "contact.phone", "contact.email"}) at the create method to hide the "id" property.

In my update API, it also has a parameter with User type. I hope Swagger will hide the "username" property in the User model because username can't be modified. So I can put an annotation @ApiImplicitModel(derived=User.class, properties={"id", "password" ,"nickname", "contact.address", "contact.phone", "contact.email"}) at the update method to hide the "username" property.

Sincerely.

[fehguy]

That's just not how this library is expected to work. Adding a mountain of annotation variables is an ugly way to use swagger.

Consider different models for input and output. They can have inheritance between them, etc, and then it's a java modeling issue.

So User as input and UserResponse as output. UserResponse may have an id field which is read-only and not acceptable for input. But let's not jam them in annotations.

[john24318]

Inheritance in models doesn't make sense. Usually my models are domain entities, and some are complex DTOs for special views. Inheritance will make my models have superclass and subclass relationship, but there is no such relationship in my create user and update user input data. They both input User model data, I just need to tell which properties are required/optional in different APIs. Thus, dynamic displaying the properties of User model is my preference.

I slightly modify my example:
// For create user:
@ApiImplicitModel(derived=User.class, required={"username", "password"}, optional={"nickname", "contact.address", "contact.phone", "contact.email"})
// For update user:
@ApiImplicitModel(derived=User.class, required="id", optional={"password", "nickname", "contact.address", "contact.phone", "contact.email"})

[fehguy]

Well I hear you, but that's just not how we want this library to evolve.

I do believe that we'll have better control over the required / optional / readOnly / writeOnly(?) on parameters but putting that in the annotation layer is really, really ugly.

[john24318]

How about support @JsonView annotation?
Can you reopen the https://github.com/swagger-api/swagger-core/issues/479 issue?