Swagger @ApiParam vs @ApiModelProperty

Java Top

Ho appena annunciato il nuovo corso Learn Spring , incentrato sui fondamenti di Spring 5 e Spring Boot 2:

>> SCOPRI IL CORSO

1. Panoramica

In questo tutorial, esamineremo brevemente le annotazioni @ApiParam e @ApiModelProperty di Swagger . Inoltre, confronteremo queste annotazioni e identificheremo l'uso corretto per ciascuna.

2. Differenza chiave

In poche parole , le annotazioni @ApiParam e @ApiModelProperty aggiungono metadati diversi a Swagger. L' annotazione @ApiParam è per i parametri di una richiesta di risorsa API, mentre @ApiModelProperty è per le proprietà del modello.

3. @ApiParam

L' annotazione @ApiParam può essere utilizzata esclusivamente con le annotazioni dei parametri JAX-RS 1.x / 2.x come @PathParam , @QueryParam , @HeaderParam , @FormParam e @BeanParam . Sebbene swagger-core scansiona queste annotazioni per impostazione predefinita, possiamo usare @ApiParam per aggiungere ulteriori dettagli sui parametri o modificare i valori mentre vengono letti dal codice.

L' annotazione @ApiParam aiuta a specificare il nome, il tipo, la descrizione (valore) e il valore di esempio del parametro. Inoltre, possiamo specificare se il parametro è obbligatorio o facoltativo.

Diamo un'occhiata al suo utilizzo:

@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; }

Diamo un'occhiata alla rappresentazione dell'interfaccia utente di Swagger per il nostro esempio @ApiParam :

Ora, diamo un'occhiata a @ApiModelProperty .

4. @ApiModelProperty

L' annotazione @ApiModelProperty ci consente di controllare definizioni specifiche di Swagger come descrizione (valore), nome, tipo di dati, valori di esempio e valori consentiti per le proprietà del modello.

Inoltre, offre ulteriori proprietà di filtraggio nel caso in cui desideriamo nascondere la proprietà in determinati scenari.

Aggiungiamo alcune proprietà del modello al campo FirstName dell'utente :

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

Ora, diamo un'occhiata alle specifiche del modello utente nell'interfaccia utente di Swagger:

5. conclusione

In questo rapido articolo, abbiamo esaminato due annotazioni Swagger che possiamo utilizzare per aggiungere metadati per i parametri e le proprietà del modello. Quindi, abbiamo esaminato un codice di esempio utilizzando tali annotazioni e abbiamo visto le loro rappresentazioni nell'interfaccia utente di Swagger.

Come sempre, tutti questi esempi di codice sono disponibili su GitHub.

Fondo Java

Ho appena annunciato il nuovo corso Learn Spring , incentrato sui fondamenti di Spring 5 e Spring Boot 2:

>> SCOPRI IL CORSO