Navedite niz žica kao parametre tijela u Swaggeru

1. Pregled

Swagger je skup specifikacija za dokumentiranje i opisivanje REST API-ja. Također pruža primjere vrijednosti za parametre krajnje točke.

U ovom uputstvu pokazat ćemo kako stvoriti zadanu vrijednost primjera za Niz nizova, jer ovo ponašanje prema zadanim postavkama nije omogućeno.

2. Navedite niz žica kao parametre tijela u Swaggeru

Problem se javlja kada želimo navesti niz nizova kao parametre tijela u Swaggeru.

Swaggerova zadana vrijednost primjera pomalo je neprozirna, kao što možemo vidjeti u uređivaču Swagger:

Dakle, ovdje vidimo da Swagger zapravo ne pokazuje primjer kako bi trebao izgledati sadržaj polja. Pogledajmo kako dodati jedan.

3. YAML

Prvo započinjemo određivanjem niza nizova u Swaggeru pomoću YAML notacije. U odjeljak sheme uključujemo vrsta: niz s predmeta String.

Da bismo bolje dokumentirali API i uputili korisnika, možemo koristiti primjer oznaka kako umetnuti vrijednosti:

parametri: - u: opis tijela: "" potrebno: istinito ime: shema imena: tip: stavke niza: vrsta: niz primjer: ["str1", "str2", "str3"]

Pogledajmo kako je naš prikaz sada informativniji:

4. Springfox

Ili možemo postići isti rezultat koristeći Springfox.

Moramo koristiti vrsta podataka i primjer u podatkovnom modelu sa @ApiModel i @ApiModelProperty napomene:

@ApiModel javna klasa Foo {private long id; @ApiModelProperty (name = "name", dataType = "List", example = "[\" str1 \ ", \" str2 \ ", \" str3 \ "]") ime privatnog popisa;

Nakon toga, također moramo označiti Kontroler kako bi Swagger ukazao na model podataka.

Pa, poslužimo se @ApiImplicitParams za to:

@RequestMapping (method = RequestMethod.POST, value = "/ foos") @ResponseStatus (HttpStatus.CREATED) @ResponseBody @ApiImplicitParams ({@ApiImplicitParam (name = "foo", value = "Popis nizova", paramType = " ", dataType =" Foo ")}) javni Foo create (@RequestBody final Foo foo) {

I to je to!

5. Zaključak

Kada dokumentiramo REST API-je, možemo imati parametre koji su nizovi nizova. U idealnom slučaju, dokumentirali bismo ih Primjerima vrijednosti.

To možemo učiniti u Swaggeru s primjer imovine. Ili, možemo koristiti primjer atribut bilješke u Springfoxu.

Kao i uvijek, kôd je dostupan na GitHub-u.