streamalism.org

Ik heb zojuist het nieuwe aangekondigd Leer de lente natuurlijk, gericht op de basisprincipes van Spring 5 en Spring Boot 2:

1. Overzicht

In deze tutorial zullen we kort kijken naar Swagger's @ApiParam en @ApiModelProperty annotaties. Verder zullen we deze annotaties vergelijken en voor elk het juiste gebruik identificeren.

2. Belangrijkste verschil

Simpel gezegd, @ApiParam en @ApiModelProperty annotaties voegen verschillende metadata toe aan Swagger. De @ApiParam annotatie is voor de parameters van een API-resourceverzoek, terwijl @ApiModelProperty is voor eigenschappen van het model.

3. @ApiParam

De @ApiParam annotatie is uitsluitend bedoeld voor gebruik met de JAX-RS 1.x / 2.x parameterannotaties zoals @PathParam, @RTLnieuws, @HeadParam, @RTLnieuws, en @BeanParam. Hoewel branie-kern scant deze annotaties standaard, kunnen we gebruiken @ApiParam om meer details over de parameters toe te voegen of om de waarden te wijzigen terwijl ze uit de code worden gelezen.

De @ApiParam annotatie helpt bij het specificeren van de naam, het type, de beschrijving (waarde) en de voorbeeldwaarde van de parameter. Bovendien kunnen we specificeren of de parameter verplicht of optioneel is.

Laten we eens kijken naar het gebruik ervan:

@RequestMapping (method = RequestMethod.POST, value = "/ createUser", produceert = "application / json; charset = UTF-8") @ResponseStatus (HttpStatus.CREATED) @ResponseBody @ApiOperation (value = "Create user", opmerkingen = "Deze methode maakt een nieuwe gebruiker") public User createUser (@ApiParam (name = "firstName", type = "String", value = "Voornaam van de gebruiker", example = "Vatsal", vereist = true) @ RequestParam String firstName) {User user = nieuwe gebruiker (firstName); terugkeer gebruiker; }

Laten we eens kijken naar de Swagger UI-weergave voor onze @ApiParam voorbeeld:

Laten we nu eens kijken @ApiModelProperty.

4. @ApiModelProperty

De @ApiModelProperty annotatie stelt ons in staat om Swagger-specifieke definities te beheren, zoals beschrijving (waarde), naam, gegevenstype, voorbeeldwaarden en toegestane waarden voor de modeleigenschappen.

Het biedt ook extra filtereigenschappen voor het geval we de eigenschap in bepaalde scenario's willen verbergen.

Laten we een paar modeleigenschappen toevoegen aan het GebruikerVoornaam veld:

@ApiModelProperty (waarde = "voornaam van de gebruiker", naam = "voornaam", dataType = "String", voorbeeld = "Vatsal") String firstName;

Laten we nu eens kijken naar de Gebruiker Specificaties van het model in de gebruikersinterface van Swagger:

5. Conclusie

In dit korte artikel hebben we gekeken naar twee Swagger-annotaties die we kunnen gebruiken om metadata voor parameters en modeleigenschappen toe te voegen. Vervolgens keken we naar een voorbeeldcode met behulp van die annotaties en zagen we hun representaties in Swagger UI.

Zoals altijd zijn al deze codevoorbeelden beschikbaar op GitHub.

Ik heb zojuist het nieuwe aangekondigd Leer de lente natuurlijk, gericht op de basisprincipes van Spring 5 en Spring Boot 2: