Spécifier un tableau de chaînes comme paramètres de corps dans Swagger

1. Vue d'ensemble

Swagger est un ensemble de spécifications pour documenter et décrire les API REST. Il fournit également des exemples de valeurs pour les paramètres de point de terminaison.

Dans ce didacticiel, nous montrerons comment produire un exemple de valeur par défaut pour les tableaux String , car ce comportement n'est pas activé par défaut.

2. Spécifiez un tableau de chaînes comme paramètres de corps dans Swagger

Le problème survient lorsque nous voulons spécifier un tableau de chaînes comme paramètres de corps dans Swagger.

La valeur d'exemple par défaut de Swagger est un peu opaque, comme nous pouvons le voir dans l'éditeur Swagger:

Donc, nous voyons ici que Swagger ne montre pas vraiment un exemple de ce à quoi le contenu du tableau devrait ressembler. Voyons comment en ajouter un.

3. YAML

Tout d'abord, nous commençons par spécifier le tableau de chaînes dans Swagger en utilisant la notation YAML. Dans la section schéma, nous incluons type: array avec des éléments String .

Pour mieux documenter l'API et instruire l'utilisateur, nous pouvons utiliser l' exemple d' étiquette indiquant comment insérer des valeurs:

parameters: - in: body description: "" required: true name: name schema: type: array items: type: string example: ["str1", "str2", "str3"]

Voyons comment notre affichage est maintenant plus informatif:

4. Springfox

Ou, nous pouvons obtenir le même résultat en utilisant Springfox.

Nous devons utiliser le dataType et l' exemple dans le modèle de données avec les annotations @ApiModel et @ApiModelProperty :

@ApiModel public class Foo { private long id; @ApiModelProperty(name = "name", dataType = "List", example = "[\"str1\", \"str2\", \"str3\"]") private List name;

Après cela, nous devons également annoter le contrôleur pour laisser Swagger pointer vers le modèle de données.

Alors, utilisons @ApiImplicitParams pour cela:

@RequestMapping(method = RequestMethod.POST, value = "/foos") @ResponseStatus(HttpStatus.CREATED) @ResponseBody @ApiImplicitParams({ @ApiImplicitParam(name = "foo", value = "List of strings", paramType = "body", dataType = "Foo") }) public Foo create(@RequestBody final Foo foo) {

Et c'est tout!

5. Conclusion

Lors de la documentation des API REST, nous pouvons avoir des paramètres qui sont des tableaux de chaînes. Idéalement, nous les documenterions avec des exemples de valeurs.

Nous pouvons le faire dans Swagger avec la propriété example . Ou, nous pouvons utiliser l' exemple d' attribut d'annotation dans Springfox.

Comme toujours, le code est disponible sur sur GitHub.