«1. Обзор

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

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

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

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

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

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

3. YAML

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

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

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

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

4. Springfox

Или мы можем добиться того же результата, используя 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.