streamalism.org

Jeg har lige annonceret det nye Lær foråret kursus med fokus på det grundlæggende i Spring 5 og Spring Boot 2:

1. Oversigt

I denne vejledning vil vi kort se på Swagger's @ApiParam og @ApiModelProperty kommentarer. Desuden sammenligner vi disse kommentarer og identificerer den korrekte brug for hver.

2. Nøgleforskel

Kort fortalt, @ApiParam og @ApiModelProperty annoteringer tilføjer forskellige metadata til Swagger. Det @ApiParam annotation er for parametrene for en API-ressourceanmodning, mens @ApiModelProperty er for modelens egenskaber.

3. @ApiParam

Det @ApiParam annotering er udelukkende til brug med JAX-RS 1.x / 2.x parameterkommentarer som @PathParam, @QueryParam, @HeaderParam, @FormParamog @BeanParam. Selvom swagger-core scanner disse kommentarer som standard, vi kan bruge @ApiParam for at tilføje flere detaljer om parametrene eller ændre værdierne, når de læses fra koden.

Det @ApiParam annotation hjælper med at specificere parameterens navn, type, beskrivelse (værdi) og eksempelværdi. Desuden kan vi specificere, om parameteren er påkrævet eller valgfri.

Lad os se på dens anvendelse:

@RequestMapping (metode = RequestMethod.POST, værdi = "/ createUser", producerer = "applikation / json; charset = UTF-8") @ResponseStatus (HttpStatus.CREATED) @ResponseBody @ApiOperation (værdi = "Opret bruger", noter = "Denne metode opretter en ny bruger") offentlig bruger createUser (@ApiParam (navn = "fornavn", type = "String", værdi = "brugerens fornavn", eksempel = "Vatsal", krævet = sand) @ RequestParam String firstName) {Bruger bruger = ny bruger (fornavn); tilbagevendende bruger }

Lad os se på Swagger UI-repræsentationen for vores @ApiParam eksempel:

Lad os nu se på @ApiModelProperty.

4. @ApiModelProperty

Det @ApiModelProperty kommentar giver os mulighed for at kontrollere Swagger-specifikke definitioner såsom beskrivelse (værdi), navn, datatype, eksempelværdier og tilladte værdier for modelegenskaberne.

Det tilbyder også yderligere filtreringsegenskaber, hvis vi vil skjule ejendommen i visse scenarier.

Lad os tilføje et par modelegenskaber til Brugerensfornavn Mark:

@ApiModelProperty (værdi = "brugerens fornavn", navn = "fornavn", dataType = "streng", eksempel = "Vatsal") Streng fornavn;

Lad os nu se på Bruger Modelens specifikationer i Swagger UI:

5. Konklusion

I denne hurtige artikel kiggede vi på to Swagger-kommentarer, som vi kan bruge til at tilføje metadata til parametre og modelegenskaber. Derefter kiggede vi på nogle prøvekoder ved hjælp af disse kommentarer og så deres repræsentationer i Swagger UI.

Som altid er alle disse kodeeksempler tilgængelige på GitHub.

Jeg har lige annonceret det nye Lær foråret kursus med fokus på det grundlæggende i Spring 5 og Spring Boot 2: