Перейти к основному содержимому

Swagger @ApiParam против @ApiModelProperty

· 2 мин. чтения

1. Обзор​

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

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

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

3. @Апипарам​

Аннотация @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 :

./0a9f278f326188b29b5030d972641757.png

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

4. @АпиМоделПроперти​

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

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

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

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

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

./2c31c7a55e00fc77df3b9fd946f7bd4b.png

5. Вывод​

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

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