«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.