Посочете масив от низове като параметри на тялото в Swagger

1. Общ преглед

Swagger е набор от спецификации за документиране и описание на REST API. Той също така предоставя примерни стойности за параметрите на крайната точка.

В този урок ще ви покажем как да се произвежда по подразбиране например стойност за String масиви, тъй като това поведение не е активирана по подразбиране.

2. Посочете масив от низове като параметри на тялото в Swagger

Проблемът възниква, когато искаме да зададем масив от низове като параметри на тялото в Swagger.

Примерната стойност на Swagger по подразбиране е малко непрозрачна, както можем да видим в редактора на Swagger:

И така, тук виждаме, че Суагър всъщност не показва пример за това как трябва да изглежда съдържанието на масива. Нека да видим как да добавим такъв.

3. ЯМЛ

Първо, започваме с определяне на масива от низове в Swagger, използвайки YAML нотация. В раздела на схемата включваме type: array с елементи 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 name;

След това също трябва да анотираме контролера, за да позволим на Суагър да сочи към модела на данните.

Така че, нека използваме @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 с примерното свойство. Или можем да използваме примерния атрибут на анотация в Springfox.

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