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.

BookController.java


              1234
            
@Tag(name = "Books", description = "API for managing books")
public class BookController {
    // struct
}

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

BookController.java


              1234
            
@Operation(summary = "Get a list of all books", description = "Returns a list of all available books")
public List<BookResponseDTO> getAllBooks() {
    return bookService.findAllBooks();
}

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

BookController.java


              12345
            
public BookResponseDTO getBookById(
        @Parameter(description = "ID of the book to retrieve", required = true)
        @PathVariable String id) {
    return bookService.getBookById(id);
}

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

BookController.java


              12345678
            
@ApiResponse(responseCode = "204", description = "Book successfully deleted")
@DeleteMapping("/{id}")
public void deleteBook(
    @Parameter(description = "ID of the book to delete", required = true)
  	@PathVariable String id
) {
    	bookService.deleteBook(id);
}

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

BookController.java


              12345678910111213
            
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "Book successfully updated"),
        @ApiResponse(responseCode = "404", description = "Book not found")
})
@PutMapping("/{id}")
public BookResponseDTO updateBook(
  		@Parameter(description = "ID of the book to update", required = true) 
		@PathVariable String id,
  @RequestBody(description = "Updated book details", required = true) BookRequestDTO book
) {
    return bookService.updateBook(id, book);
}

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.

Tutto è chiaro?

Grazie per i tuoi commenti!

Sezione 3. Capitolo 7

Chieda ad AI

Chieda pure quello che desidera o provi una delle domande suggerite per iniziare la nostra conversazione

Awesome!

Completion rate improved to 3.45

Scorri per mostrare il menu

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!

Utilizzo delle annotazioni

Rivediamo brevemente le annotazioni trattate in questo capitolo:

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

BookController.java


              1234
            
@Tag(name = "Books", description = "API for managing books")
public class BookController {
    // struct
}

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

BookController.java


              1234
            
@Operation(summary = "Get a list of all books", description = "Returns a list of all available books")
public List<BookResponseDTO> getAllBooks() {
    return bookService.findAllBooks();
}

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

BookController.java


              12345
            
public BookResponseDTO getBookById(
        @Parameter(description = "ID of the book to retrieve", required = true)
        @PathVariable String id) {
    return bookService.getBookById(id);
}

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

BookController.java


              12345678
            
@ApiResponse(responseCode = "204", description = "Book successfully deleted")
@DeleteMapping("/{id}")
public void deleteBook(
    @Parameter(description = "ID of the book to delete", required = true)
  	@PathVariable String id
) {
    	bookService.deleteBook(id);
}

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

BookController.java


              12345678910111213
            
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "Book successfully updated"),
        @ApiResponse(responseCode = "404", description = "Book not found")
})
@PutMapping("/{id}")
public BookResponseDTO updateBook(
  		@Parameter(description = "ID of the book to update", required = true) 
		@PathVariable String id,
  @RequestBody(description = "Updated book details", required = true) BookRequestDTO book
) {
    return bookService.updateBook(id, book);
}

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.

Tutto è chiaro?

Grazie per i tuoi commenti!

Sezione 3. Capitolo 7

Test delle API RESTful

Introduzione a Swagger

Utilizzo delle annotazioni

Progetto

Riepilogo

Awesome!

Test delle API RESTful

Introduzione a Swagger

Utilizzo delle annotazioni

Progetto

Riepilogo