Both the following annotations work for adding metadata to swagger-ui docs. Which one should be prefered, and why?
public class MyReq {
@ApiModelProperty(required = true, value = "the persons name")
@ApiParam(required = true, value = "the persons name")
private String name;
}
@RestController
public class MyServlet {
@RequestMapping("/")
public void test(MyReq req) {
}
}
There is a huge difference between the two. They are both used to add metadata to swagger but they add different metadata.
@ApiParam is for parameters. It is usually defined in the API Resource request class.
Example of @ApiParam:
/users?age=50
it can be used to define parameter age and the following fields:
- paramType: query
- name: age
- description: age of the user
- required: true
@ApiModelProperty is used for adding properties for models.
You will use it in your model class on the model properties.
Example:
model User has name and age as properties: name and age then for each property you can define the following:
For age:
- type: integer,
- format": int64,
- description: age of the user,
Check out the fields each denote in the swagger objects:
@ApiModelProperty- https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md#529-property-object
@ApiParam - https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md#524-parameter-object