«1. Обзор

В этом руководстве мы кратко рассмотрим аннотации Swagger @ApiParam и @ApiModelProperty. Кроме того, мы сравним эти аннотации и определим правильное использование для каждого из них.

2. Ключевое отличие

Проще говоря, аннотации @ApiParam и @ApiModelProperty добавляют разные метаданные в Swagger. Аннотация @ApiParam предназначена для параметров запроса ресурсов API, а @ApiModelProperty — для свойств модели.

3. @ApiParam

Аннотация @ApiParam предназначена исключительно для использования с аннотациями параметров JAX-RS 1.x/2.x, такими как @PathParam, @QueryParam, @HeaderParam, @FormParam и @BeanParam. Хотя swagger-core сканирует эти аннотации по умолчанию, мы можем использовать @ApiParam, чтобы добавить дополнительные сведения о параметрах или изменить значения по мере их считывания из кода.

Аннотация @ApiParam помогает указать имя, тип, описание (значение) и пример значения параметра. Кроме того, мы можем указать, является ли параметр обязательным или необязательным.

Давайте посмотрим на его использование: 

@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;
}

Давайте посмотрим на представление пользовательского интерфейса Swagger для нашего примера @ApiParam:

Теперь давайте посмотрим на @ApiModelProperty.

4. @ApiModelProperty

Аннотация @ApiModelProperty позволяет нам управлять специфичными для Swagger определениями, такими как описание (значение), имя, тип данных, примеры значений и допустимые значения для свойств модели.

Кроме того, он предлагает дополнительные свойства фильтрации на случай, если мы захотим скрыть это свойство в определенных сценариях.

Давайте добавим несколько свойств модели в поле User’s firstName: 

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

Теперь давайте посмотрим на спецификации модели пользователя в пользовательском интерфейсе Swagger:

5. Заключение

В этой быстрой статье мы рассмотрели две аннотации Swagger, которые мы можем использовать для добавления метаданных для параметров и свойств модели. Затем мы рассмотрели пример кода с использованием этих аннотаций и увидели их представление в пользовательском интерфейсе Swagger.

Как всегда, все эти примеры кода доступны на GitHub.