Swagger @ApiParam vs @ApiModelProperty

Java Top

Jeg kunngjorde nettopp det nye Lær våren kurs, med fokus på det grunnleggende i vår 5 og vårstøvel 2:

>> KONTROLLER KURSET

1. Oversikt

I denne opplæringen vil vi kort se på Swagger's @ApiParam og @ApiModelProperty kommentarer. Videre vil vi sammenligne disse kommentarene og identifisere riktig bruk for hver.

2. Nøkkelforskjell

For å si det enkelt, @ApiParam og @ApiModelProperty merknader legger til forskjellige metadata i Swagger. De @ApiParam merknader er for parameterne for en API-ressursforespørsel, mens @ApiModelProperty er for egenskapene til modellen.

3. @ApiParam

De @ApiParam merknader er kun til bruk med JAX-RS 1.x / 2.x parameterkommentarer som @PathParam, @QueryParam, @HeaderParam, @FormParam, og @BeanParam. Selv om swagger-core skanner disse merknadene som standard, vi kan bruke @ApiParam for å legge til flere detaljer om parametrene eller endre verdiene når de leses fra koden.

De @ApiParam kommentar hjelper deg med å spesifisere navn, type, beskrivelse (verdi) og eksempelverdi for parameteren. Videre kan vi spesifisere om parameteren er nødvendig eller valgfri.

La oss se på bruken:

@RequestMapping (method = RequestMethod.POST, value = "/ createUser", produserer = "application / json; charset = UTF-8") @ResponseStatus (HttpStatus.CREATED) @ResponseBody @ApiOperation (value = "Create user", notater = "Denne metoden oppretter en ny bruker") offentlig bruker createUser (@ApiParam (name = "firstName", type = "String", value = "First Name of the user", example = "Vatsal", required = true) @ RequestParam String firstName) {User user = new User (firstName); retur bruker; }

La oss se på Swagger UI-representasjonen for vår @ApiParam eksempel:

La oss nå se på @ApiModelProperty.

4. @ApiModelProperty

De @ApiModelProperty kommentar lar oss kontrollere Swagger-spesifikke definisjoner som beskrivelse (verdi), navn, datatype, eksempelverdier og tillatte verdier for modellegenskapene.

Det tilbyr også flere filtreringsegenskaper i tilfelle vi ønsker å skjule eiendommen i visse scenarier.

La oss legge til noen modellegenskaper i Brukerensfornavn felt:

@ApiModelProperty (verdi = "brukerens fornavn", navn = "fornavn", dataType = "streng", eksempel = "Vatsal") streng fornavn;

La oss ta en titt på Bruker Modellens spesifikasjoner i Swagger UI:

5. Konklusjon

I denne raske artikkelen så vi på to Swagger-merknader vi kan bruke til å legge til metadata for parametere og modellegenskaper. Så så vi på noen eksempler på koden ved å bruke disse kommentarene og så representasjonene i Swagger UI.

Som alltid er alle disse kodeeksemplene tilgjengelige på GitHub.

Java bunn

Jeg kunngjorde nettopp det nye Lær våren kurs, med fokus på det grunnleggende i vår 5 og vårstøvel 2:

>> KONTROLLER KURSET

$config[zx-auto] not found$config[zx-overlay] not found