Specificare una matrice di stringhe come parametri del corpo in Swagger

1. Panoramica

Swagger è un insieme di specifiche per documentare e descrivere le API REST. Fornisce inoltre valori di esempio per i parametri dell'endpoint.

In questo tutorial, mostreremo come produrre un valore di esempio predefinito per gli array di stringhe , poiché questo comportamento non è abilitato per impostazione predefinita.

2. Specificare un array di stringhe come parametri del corpo in Swagger

Il problema sorge quando vogliamo specificare un array di stringhe come parametri del corpo in Swagger.

Il valore di esempio predefinito di Swagger è un po 'opaco, come possiamo vedere nell'editor di Swagger:

Quindi, qui vediamo che Swagger non mostra davvero un esempio di come dovrebbe apparire il contenuto dell'array. Vediamo come aggiungerne uno.

3. YAML

In primo luogo, iniziamo specificando l'array di stringhe in Swagger utilizzando la notazione YAML. Nella sezione dello schema, includiamo type: array con elementi String .

Per documentare meglio l'API e istruire l'utente, possiamo utilizzare l' etichetta di esempio su come inserire i valori:

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

Vediamo come il nostro display è ora più informativo:

4. Springfox

Oppure possiamo ottenere lo stesso risultato usando Springfox.

Dobbiamo usare dataType ed esempio nel modello dati con le annotazioni @ApiModel e @ApiModelProperty :

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

Dopodiché, dobbiamo anche annotare il controller per consentire a Swagger di puntare al modello di dati.

Quindi, usiamo @ApiImplicitParams per questo:

@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) {

E questo è tutto!

5. conclusione

Durante la documentazione delle API REST, potremmo avere parametri che sono array di stringhe. Idealmente, li documenteremmo con valori di esempio.

Possiamo farlo in Swagger con la proprietà example . Oppure possiamo usare l' attributo annotation di esempio in Springfox.

Come sempre, il codice è disponibile su GitHub.