Swagger @ApiParam vs @ApiModelProperty: 详解与比较

1. Overview

In this tutorial, we will briefly look at Swagger’s @ApiParam and @ApiModelProperty annotations. Furthermore, we will compare these annotations and identify the correct usage for each.

2. Key Difference

Simply put, @ApiParam and @ApiModelProperty annotations add different metadata to Swagger.** The @ApiParam annotation is for the parameters of an API resource request, whereas @ApiModelProperty is for properties of the model.

3. @ApiParam

The @ApiParam annotation is for use solely with the JAX-RS 1.x/2.x parameter annotations like @PathParam, @QueryParam, @HeaderParam, @FormParam, and @BeanParam. Although swagger-core scans these annotations by default, we can use @ApiParam to add more details about the parameters or change the values as they are read from the code.

The @ApiParam annotation helps to specify the name, type, description (value), and example value of the parameter. Moreover, we can specify whether the parameter is required or optional.

Let’s look at its usage:

@RequestMapping(
    method = RequestMethod.POST,
    value = "/createUser",
    produces = "application/json; charset=UTF-8")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
@ApiOperation(value = "Create user",
  notes = "This method creates a new user")
public User createUser(
  @ApiParam(
    name =  "firstName",
    type = "String",
    value = "First Name of the user",
    example = "Vatsal",
    required = true)
  @RequestParam String firstName) {
 
    User user = new User(firstName);
    return user;
}

Let’s look at the Swagger UI representation for our @ApiParam example:

Now, let’s look at @ApiModelProperty.

4. @ApiModelProperty

The @ApiModelProperty annotation allows us to control Swagger-specific definitions such as description (value), name, data type, example values, and allowed values for the model properties.

Also, it offers additional filtering properties in case we want to hide the property in certain scenarios.

Let’s add a few model properties to the User’s firstName field:

@ApiModelProperty(
  value = "first name of the user",
  name = "firstName",
  dataType = "String",
  example = "Vatsal")
String firstName;

Now, let’s take a look at the User Model’s specifications in Swagger UI:

5. Conclusion

In this quick article, we looked at two Swagger annotations we can use to add metadata for parameters and model properties. Then, we looked at some sample code using those annotations and saw their representations in Swagger UI.

As always, all these code samples are available over on GitHub.