Nel capitolo precedente, siamo stati introdotti a Swagger e a come utilizzarlo. In questo capitolo, esploreremo il suo utilizzo tramite un esempio pratico e completeremo completamente la nostra prima REST API!

Introduzione a Swagger

Nel video, sei stato introdotto all'interfaccia principale di Swagger e a come interagire con essa.

Per le metodologie che accettano un request body, Swagger genera automaticamente il JSON in base all'oggetto che l'endpoint corrente riceve.

Inoltre, se sono presenti parametri nell'URL, è possibile specificarli facilmente nei campi corrispondenti.

Swagger mostra anche i possibili codici di stato per l'endpoint e specifica il tipo di ritorno dell'oggetto (JSON/XML).

E, cosa più importante, non è stato necessario scrivere alcun codice aggiuntivo per generare questa documentazione!

È sufficiente aggiungere la dipendenza e configurarla se necessario (anche se spesso non è richiesta alcuna configurazione) per ottenere automaticamente la documentazione per la propria REST API!

Utilizzo delle annotazioni

Rivediamo brevemente le annotazioni trattate in questo capitolo:

@Tag – Raggruppa gli endpoint correlati e aggiunge una descrizione ad essi.

@Operation – Descrive uno specifico metodo API, includendo il suo scopo e una breve descrizione.

@Parameter – Descrive i parametri del metodo, come variabili di percorso, parametri di query e simili.

@ApiResponse – Descrive una singola specifica possibile risposta, inclusi il codice di risposta e la sua descrizione.

@ApiResponses – Definisce un insieme di possibili risposte per il metodo, inclusi i codici di stato e le descrizioni.

Progetto

Viene fornito anche un link al progetto nel caso in cui qualcosa non funzioni o se si desidera esplorarlo più nel dettaglio:

Riepilogo

Swagger consente la generazione automatica di una documentazione dettagliata per la propria API, rendendola più semplice da utilizzare e testare.

Con annotazioni come @Operation, @ApiResponse e @Parameter, è possibile descrivere il comportamento di metodi, parametri e possibili risposte senza aggiungere codice extra. Questo rende la propria REST API più chiara e più accessibile agli sviluppatori.