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) {
}
}
@Target(value={PARAMETER,METHOD,FIELD}) @Retention(value=RUNTIME) public @interface ApiParam. Adds additional meta-data for operation parameters. This annotation can be used only in combination of JAX-RS 1. x/2. x annotations.
Annotation Type ApiModel Provides additional information about Swagger models. Classes will be introspected automatically as they are used as types in operations, but you may want to manipulate the structure of the models.
Add Description to Methods and Parameters. @ApiOperation defines the properties of an API method. We added a name to the operation using the value property, and a description using the notes property. @ApiResponses is used to override the default messages that accompany the response codes.
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:
@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:
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
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With