1. Overview

1.概述

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.

在本教程中，我们将简要介绍 Swagger 的 @ApiParam 和 @ApiModelProperty 注解。此外，我们将比较这些注解，并确定每个注解的正确用法。

2. Key Difference

2.关键差异

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.

简单地说，@ApiParam和@ApiModelProperty注解为Swagger添加了不同的元数据。@ApiParam注解是针对API资源请求的参数，而@ApiModelProperty是针对模型的属性。

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.

@ApiParam注解仅用于JAX-RS 1.x/2.x参数注解，如@PathParam、@QueryParam、@HeaderParam、@FormParam、@BeanParam。尽管swagger-core默认扫描了这些注解，但我们可以使用@ApiParam来添加更多关于参数的细节，或者在从代码中读取参数时改变其值。

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.

@ApiParam注解有助于指定参数的名称、类型、描述（值）和示例值。此外，我们可以指定参数是必需的还是可选的。

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:

让我们看看Swagger UI对我们@ApiParam例子的表示。

Now, let’s look at @ApiModelProperty.

现在，让我们看看@ApiModelProperty。

4. @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.

@ApiModelProperty注解允许我们控制Swagger特定的定义，如描述（值）、名称、数据类型、示例值和模型属性的允许值。

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:

让我们给User’s firstName字段添加一些模型属性。

@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:

现在，让我们看看Swagger UI中User Model的规格。

5. Conclusion

5.总结

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.

在这篇快速文章中，我们看了两个Swagger注解，我们可以用它们来为参数和模型属性添加元数据。然后，我们看了一些使用这些注解的示例代码，并看到它们在Swagger UI中的表现。

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

一如既往，所有这些代码样本都可以在GitHub上找到。