Swagger @ApiParam vs @ApiModelProperty
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 KURSET1. 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