streamalism.org

1. Oversikt

Swagger er et sett med spesifikasjoner for å dokumentere og beskrive REST APIer. Det gir også eksempelverdier for endepunktparametrene.

I denne opplæringen viser vi hvordan du produserer en standardeksempelverdi for String arrays, ettersom denne oppførselen ikke er aktivert som standard.

2. Spesifiser en rekke strenger som kroppsparametere i Swagger

Problemet oppstår når vi vil spesifisere en rekke strenger som kroppsparametere i Swagger.

Swagger's standard eksempelverdi er litt ugjennomsiktig, som vi kan se i Swagger-redigereren:

Så her ser vi at Swagger egentlig ikke viser et eksempel på hvordan matriseinnholdet burde se ut. La oss se hvordan du legger til en.

3. YAML

For det første begynner vi med å spesifisere rekkefølgen av strenger i Swagger ved hjelp av YAML-notasjon. I skjemadelen inkluderer vi type: matrise med gjenstander String.

For å bedre dokumentere API og instruere brukeren, kan vi bruke eksempel etikett for hvordan du setter inn verdier:

parametere: - in: body description: "" required: true name: name schema: type: array items: type: string example: ["str1", "str2", "str3"]

La oss se hvordan skjermen vår nå er mer informativ:

4. Springfox

Eller vi kan oppnå det samme resultatet ved hjelp av Springfox.

Vi må bruke data-type 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;

Etter det må vi også kommentere Kontroller å la Swagger peke på datamodellen.

Så, la oss bruke @ApiImplicitParams for det:

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

Og det er det!

5. Konklusjon

Når vi dokumenterer REST API-ene, kan det hende vi har parametere som er strengmatriser. Ideelt sett vil vi dokumentere disse med eksempelverdier.

Vi kan gjøre dette i Swagger med eksempel eiendom. Eller vi kan bruke eksempel merknadsattributt i Springfox.

Som alltid er koden tilgjengelig på GitHub.