Use @ApiParam or @ApiModelProperty in swagger?

Question

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) {

   }
}

Answer 1

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