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

Укажите массив строк в качестве параметров тела в Swagger

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

1. Обзор​

Swagger — это набор спецификаций для документирования и описания REST API. Он также предоставляет примеры значений для параметров конечной точки.

В этом руководстве мы покажем, как создать пример значения по умолчанию для массивов строк , поскольку это поведение не включено по умолчанию.

2. Укажите массив строк в качестве параметров тела в Swagger​

Проблема возникает, когда мы хотим указать массив строк в качестве параметров тела в Swagger.

Значение примера Swagger по умолчанию немного непрозрачно, как мы можем видеть в редакторе Swagger :

./fc1acc668db339dfe0a941aaaf3e39ef.jpg

Итак, здесь мы видим, что Swagger на самом деле не показывает пример того, как должно выглядеть содержимое массива. Давайте посмотрим, как добавить один.

3. ЯМЛ​

Во-первых, мы начнем с указания массива строк в Swagger, используя нотацию YAML. В разделе схемы мы включаем тип: массив с элементами String .

Чтобы лучше задокументировать API и проинструктировать пользователя, мы можем использовать метку примера того, как вставлять значения:

parameters:
  - in: body
    description: ""
    required: true
    name: name
    schema:
      type: array
      items:
        type: string
      example: ["str1", "str2", "str3"]

Посмотрим, насколько наш дисплей стал более информативным:

./71b09294ffd7c0cd61c9363bbc1c4df8.jpg

4. Спрингфокс​

Или мы можем добиться того же результата, используя Springfox .

Нам нужно использовать dataType и пример в модели данных с аннотациями @ApiModel и @ApiModelProperty :

@ApiModel
public class Foo {
    private long id;
    @ApiModelProperty(name = "name", dataType = "List", example = "[\"str1\", \"str2\", \"str3\"]")
    private List<String> name;

После этого нам также нужно аннотировать контроллер , чтобы Swagger указывал на модель данных.

Итак, давайте использовать для этого @ApiImplicitParams :

@RequestMapping(method = RequestMethod.POST, value = "/foos")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
@ApiImplicitParams({ @ApiImplicitParam(name = "foo", 
  value = "List of strings", paramType = "body", dataType = "Foo") })
public Foo create(@RequestBody final Foo foo) {

Вот и все!

5. Вывод​

При документировании REST API у нас могут быть параметры, представляющие собой строковые массивы. В идеале мы должны задокументировать их с помощью примеров значений.

Мы можем сделать это в Swagger с помощью свойства example . Или мы можем использовать пример атрибута аннотации в Springfox.

Как всегда, код доступен на GitHub .