1. Обзор
Swagger – это набор спецификаций для документирования и описания API REST. Он также предоставляет примеры значений параметров конечной точки.
В этом руководстве мы покажем, как создать пример значения по умолчанию для массивов String , поскольку это поведение не включено по умолчанию.
2. Укажите массив строк в качестве параметров тела в Swagger
Проблема возникает, когда мы хотим указать массив строк в качестве параметров тела в Swagger.
Пример значения Swagger по умолчанию немного непрозрачен, как мы можем видеть в редакторе Swagger :
Итак, здесь мы видим, что Swagger на самом деле не показывает пример того, как должно выглядеть содержимое массива. Давайте посмотрим, как его добавить.
3. ЯМЛ
Во-первых, мы начнем с указания массива строк в Swagger с использованием нотации YAML. В разделе схемы мы включаем тип: массив с строкой элементов .
Чтобы лучше документировать API и инструктировать пользователя, мы можем использовать метку example о том, как вставлять значения:
parameters:
- in: body
description: ""
required: true
name: name
schema:
type: array
items:
type: string
example: ["str1", "str2", "str3"]Давайте посмотрим, насколько наш дисплей стал более информативным:
4. Спрингфокс
Или мы можем достичь того же результата, используя Springfox .
Нам нужно использовать тип данных и пример в модели данных с @ApiModel и @ApiModelProperty аннотациями:
@ApiModel
public class Foo {
private long id;
@ApiModelProperty(name = "name", dataType = "List", example = "[\"str1\", \"str2\", \"str3\"]")
private List 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. Заключение
При документировании API REST у нас могут быть параметры, которые являются строковыми массивами. В идеале мы бы задокументировали их с помощью примеров значений.
Мы можем сделать это в Swagger с помощью свойства example . Или мы можем использовать атрибут example annotation в Springfox.
Как всегда, код доступен на GitHub .