streamalism.org

1. Prehľad

Swagger je súbor špecifikácií na dokumentovanie a popisovanie rozhraní REST API. Poskytuje tiež vzorové hodnoty parametrov koncového bodu.

V tomto tutoriáli si ukážeme, ako vytvoriť predvolenú vzorovú hodnotu pre String polia, pretože toto správanie nie je predvolene povolené.

2. Zadajte pole reťazcov ako parametre tela v Swagger

Problém nastáva, keď chceme v Swagger špecifikovať pole reťazcov ako parametre tela.

Swaggerova predvolená vzorová hodnota je trochu nepriehľadná, ako vidíme v editore Swagger:

Takže tu vidíme, že Swagger skutočne neukazuje príklad toho, ako by mal vyzerať obsah poľa. Pozrime sa, ako jeden pridať.

3. YAML

Najprv začneme zadaním poľa reťazcov v Swaggerovi pomocou YAML notácie. V časti schéma zahrňujeme typ: pole s položky Reťazec.

Na lepšie zdokumentovanie API a poučenie používateľa môžeme použiť príklad štítok ako vložiť hodnoty:

parametre: - v: popis tela: "" povinné: skutočné meno: schéma názvu: typ: položky poľa: typ: príklad reťazca: ["str1", "str2", "str3"]

Pozrime sa, ako je teraz náš displej informatívnejší:

4. Springfox

Alebo môžeme rovnaký výsledok dosiahnuť pomocou Springfoxu.

Musíme použiť Dátový typ a príklad v dátovom modeli s @ApiModel a @ApiModelProperty anotácie:

@ApiModel verejná trieda Foo {private long id; @ApiModelProperty (name = "name", dataType = "List", example = "[\" str1 \ ", \" str2 \ ", \" str3 \ "]") súkromné ​​meno zoznamu;

Potom musíme tiež anotovať Kontrolór aby Swagger ukázal na dátový model.

Takže poďme @ApiImplicitParams pre to:

@RequestMapping (method = RequestMethod.POST, value = "/ foos") @ResponseStatus (HttpStatus.CREATED) @ResponseBody @ApiImplicitParams ({@ApiImplicitParam (name = "foo", value = "Zoznam reťazcov", paramType = "telo") ", dataType =" Foo ")}) public Foo create (@RequestBody final Foo foo) {

A je to!

5. Záver

Pri dokumentovaní rozhraní REST API môžeme mať parametre, ktoré sú reťazcovými poľami. V ideálnom prípade by sme ich dokumentovali s príkladnými hodnotami.

Môžeme to urobiť v Swagger s príklad nehnuteľnosť. Alebo môžeme použiť príklad atribút anotácie v Springfox.

Ako vždy, kód je k dispozícii na GitHub.