16

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

   }
}
risingTide
  • 1,754
  • 7
  • 31
  • 60
membersound
  • 81,582
  • 193
  • 585
  • 1,120

1 Answers1

20

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

slal
  • 2,657
  • 18
  • 29
  • 1
    So and for `spring-mvc` when having a `bean` as get-query parameter model: which one should I use on the bean fields? Because `MyReq` is both a "API Resource" and a "model class" (spring automatically maps the get-query parameters to the bean, behind the surface). – membersound Jun 13 '17 at 18:03
  • I think you would use both then, because you will want to have properties and parameters both in your swagger-ui/swagger json and as mentioned above both have different uses. – slal Jun 13 '17 at 18:24
  • 1
    Ok, I probably misunderstood your explaination. So clarify: when you speak of a "model class", you actually mean the "webservice response class", right? And thus, the `@ApiParam` is to be applied on the *request*, and the `@ApiModelProperty` on the response fields. Correct? So `MyReq` is of course no *model class* and thus I should use ApiParam. – membersound Jun 14 '17 at 07:31
  • Yes, @ApiParam is on request, on the parameters sent by the user – slal Jun 14 '17 at 14:53
  • I just noticed `@ApiParam(hidden = true)` only works for `@GetMapping` servlets. The param is still shown for `@PostMapping`. I therefore changed all annotations to `@ApiModelProperty(hidden = true)` on both request + response beans. That hides the fields for both get+post. – membersound Jul 20 '17 at 12:24
  • "ApiParam is for parameters." I'm pretty sure PathParam is for parameters. If your endpoint consumes text/plain, ApiParam can be used to get request body content. So I don't think this is entirely right.. – Alkanshel Apr 26 '18 at 19:45