streamalism.org

1. Oversigt

Swagger er et sæt specifikationer til dokumentation og beskrivelse af REST API'er. Det giver også eksempelværdier for slutpunktsparametrene.

I denne vejledning viser vi, hvordan man fremstiller en standardeksempelværdi til Snor arrays, da denne opførsel ikke er aktiveret som standard.

2. Angiv en række strenge som kropsparametre i Swagger

Problemet opstår, når vi vil specificere en række strenge som kropsparametre i Swagger.

Swaggers standardeksempelværdi er lidt uigennemsigtig, som vi kan se i Swagger-editoren:

Så her ser vi, at Swagger ikke rigtig viser et eksempel på, hvordan arrayindholdet skal se ud. Lad os se, hvordan du tilføjer en.

3. YAML

For det første starter vi med at specificere række strenge i Swagger ved hjælp af YAML-notation. I skemaafsnittet inkluderer vi type: matrix med varer String.

For bedre at kunne dokumentere API'en og instruere brugeren kan vi bruge eksempel etiket for, hvordan du indsætter værdier:

parametre: - in: body beskrivelse: "" krævet: sandt navn: navneskema: type: array items: type: string eksempel: ["str1", "str2", "str3"]

Lad os se, hvordan vores skærm nu er mere informativ:

4. Springfox

Eller vi kan opnå det samme resultat ved hjælp af Springfox.

Vi er nødt til at bruge datatype og eksempel i datamodellen med @ApiModel og @ApiModelProperty kommentarer:

@ApiModel offentlig klasse Foo {privat lang id; @ApiModelProperty (navn = "navn", dataType = "Liste", eksempel = "[\" str1 \ ", \" str2 \ ", \" str3 \ "]") privat listenavn;

Derefter skal vi også kommentere Controller at lade Swagger pege på datamodellen.

Så lad os bruge det @ApiImplicitParams for det:

@RequestMapping (metode = RequestMethod.POST, værdi = "/ foos") @ResponseStatus (HttpStatus.CREATED) @ResponseBody @ApiImplicitParams ({@ApiImplicitParam (name = "foo", value = "List of strings", paramType = "body) ", dataType =" Foo ")}) offentlig Foo opretter (@RequestBody endelig Foo foo) {

Og det er det!

5. Konklusion

Når vi dokumenterer REST API'erne, kan vi have parametre, der er strengarrays. Ideelt set ville vi dokumentere disse med eksempelværdier.

Vi kan gøre dette i Swagger med eksempel ejendom. Eller vi kan bruge eksempel annotationsattribut i Springfox.

Som altid er koden tilgængelig på GitHub.