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.