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 UI для нашего @ApiParam примера:
Теперь давайте посмотрим на @ApiModelProperty .
4. @ApiModelProperty
@ApiModelProperty аннотация позволяет нам управлять определениями, специфичными для Swagger, такими как описание (значение), имя, тип данных, примерные значения и разрешенные значения для свойств модели.
Кроме того, он предлагает дополнительные свойства фильтрации на случай, если мы захотим скрыть это свойство в определенных сценариях.
Давайте добавим несколько свойств модели в поле User /first Name :
@ApiModelProperty( value = "first name of the user", name = "firstName", dataType = "String", example = "Vatsal") String firstName;
Теперь давайте взглянем на спецификации модели User в пользовательском интерфейсе Swagger:
5. Заключение
В этой краткой статье мы рассмотрели две аннотации Swagger, которые мы можем использовать для добавления метаданных для параметров и свойств модели. Затем мы просмотрели некоторые примеры кода, использующие эти аннотации, и увидели их представления в пользовательском интерфейсе Swagger.
Как всегда, все эти примеры кода доступны на GitHub .