Swagger @ApiParam vs @ApiModelProperty

Haut Java

Je viens d'annoncer le nouveau cours Learn Spring , axé sur les principes de base de Spring 5 et Spring Boot 2:

>> VOIR LE COURS

1. Vue d'ensemble

Dans ce didacticiel, nous examinerons brièvement les annotations @ApiParam et @ApiModelProperty de Swagger . De plus, nous comparerons ces annotations et identifierons l'utilisation correcte de chacune.

2. Différence clé

En termes simples, les annotations @ApiParam et @ApiModelProperty ajoutent différentes métadonnées à Swagger. L' annotation @ApiParam concerne les paramètres d'une demande de ressource API, tandis que @ApiModelProperty concerne les propriétés du modèle.

3. @ApiParam

L' annotation @ApiParam est à utiliser uniquement avec les annotations de paramètres JAX-RS 1.x / 2.x telles que @PathParam , @QueryParam , @HeaderParam , @FormParam et @BeanParam . Bien que swagger-core analyse ces annotations par défaut, nous pouvons utiliser @ApiParam pour ajouter plus de détails sur les paramètres ou modifier les valeurs à mesure qu'elles sont lues à partir du code.

L' annotation @ApiParam permet de spécifier le nom, le type, la description (valeur) et l'exemple de valeur du paramètre. De plus, nous pouvons spécifier si le paramètre est obligatoire ou facultatif.

Regardons son utilisation:

@RequestMapping( method = RequestMethod.POST, value = "/createUser", produces = "application/json; charset=UTF-8") @ResponseStatus(HttpStatus.CREATED) @ResponseBody @ApiOperation(value = "Create user", notes = "This method creates a new user") public User createUser( @ApiParam( name = "firstName", type = "String", value = "First Name of the user", example = "Vatsal", required = true) @RequestParam String firstName) { User user = new User(firstName); return user; }

Regardons la représentation de l'interface utilisateur Swagger pour notre exemple @ApiParam :

Maintenant, regardons @ApiModelProperty .

4. @ApiModelProperty

L' annotation @ApiModelProperty nous permet de contrôler les définitions spécifiques à Swagger telles que la description (valeur), le nom, le type de données, les exemples de valeurs et les valeurs autorisées pour les propriétés du modèle.

En outre, il offre des propriétés de filtrage supplémentaires au cas où nous souhaiterions masquer la propriété dans certains scénarios.

Ajoutons quelques propriétés de modèle au champ firstName de l' utilisateur :

@ApiModelProperty( value = "first name of the user", name = "firstName", dataType = "String", example = "Vatsal") String firstName;

Jetons maintenant un coup d'œil aux spécifications du modèle utilisateur dans l'interface utilisateur de Swagger:

5. Conclusion

Dans cet article rapide, nous avons examiné deux annotations Swagger que nous pouvons utiliser pour ajouter des métadonnées pour les paramètres et les propriétés du modèle. Ensuite, nous avons examiné un exemple de code utilisant ces annotations et vu leurs représentations dans Swagger UI.

Comme toujours, tous ces exemples de code sont disponibles à l'adresse over sur GitHub.

Fond Java

Je viens d'annoncer le nouveau cours Learn Spring , axé sur les principes de base de Spring 5 et Spring Boot 2:

>> VOIR LE COURS