Dans le chapitre précédent, nous avons été introduits à Swagger et à la manière de l'utiliser. Dans ce chapitre, nous allons explorer son utilisation à travers un exemple pratique et finaliser notre première API REST !

Démarrage avec Swagger

Dans la vidéo, une présentation de l'interface principale de Swagger et de la manière d'interagir avec celle-ci a été réalisée.

Pour les méthodes acceptant un corps de requête, Swagger génère automatiquement du JSON basé sur l'objet que l'endpoint courant reçoit.

De plus, si des paramètres sont présents dans l’URL, il est simple de les spécifier dans les champs correspondants.

Swagger affiche également les codes d’état possibles pour l’endpoint et précise le type de retour de l’objet (JSON/XML).

Et surtout—aucune écriture de code supplémentaire n’est nécessaire pour générer cette documentation !

Il suffit simplement d’ajouter la dépendance et de la configurer si besoin (bien qu’aucune configuration ne soit souvent requise) pour obtenir automatiquement une documentation pour votre API REST !

Utilisation des annotations

Passons brièvement en revue les annotations abordées dans ce chapitre :

@Tag – Regroupe les endpoints associés et leur ajoute une description.

BookController.java


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

@Operation – Décrit une méthode API spécifique, en précisant son objectif et une brève description.

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 – Décrit les paramètres de méthode, tels que les variables de chemin, les paramètres de requête, etc.

BookController.java


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

@ApiResponse – Décrit une réponse possible unique, incluant le code de réponse et sa description.

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 – Définit un ensemble de réponses possibles pour la méthode, y compris les codes d'état et les descriptions.

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

Projet

Un lien vers le projet est également fourni au cas où quelque chose ne fonctionnerait pas ou si vous souhaitez l'examiner plus en détail :

Résumé

Swagger permet la génération automatique d'une documentation détaillée pour votre API, ce qui la rend plus facile à utiliser et à tester.

Grâce à des annotations telles que @Operation, @ApiResponse et @Parameter, il est possible de décrire le comportement des méthodes, des paramètres et des réponses possibles sans ajouter de code supplémentaire. Cela rend votre API REST plus claire et plus accessible aux développeurs.

Tout était clair ?

Merci pour vos commentaires !

Section 3. Chapitre 7

Demandez à l'IA

Posez n'importe quelle question ou essayez l'une des questions suggérées pour commencer notre discussion

Awesome!

Completion rate improved to 3.45

Glissez pour afficher le menu

Démarrage avec Swagger

Dans la vidéo, une présentation de l'interface principale de Swagger et de la manière d'interagir avec celle-ci a été réalisée.

Pour les méthodes acceptant un corps de requête, Swagger génère automatiquement du JSON basé sur l'objet que l'endpoint courant reçoit.

De plus, si des paramètres sont présents dans l’URL, il est simple de les spécifier dans les champs correspondants.

Swagger affiche également les codes d’état possibles pour l’endpoint et précise le type de retour de l’objet (JSON/XML).

Et surtout—aucune écriture de code supplémentaire n’est nécessaire pour générer cette documentation !

Utilisation des annotations

Passons brièvement en revue les annotations abordées dans ce chapitre :

@Tag – Regroupe les endpoints associés et leur ajoute une description.

BookController.java


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

@Operation – Décrit une méthode API spécifique, en précisant son objectif et une brève description.

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 – Décrit les paramètres de méthode, tels que les variables de chemin, les paramètres de requête, etc.

BookController.java


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

@ApiResponse – Décrit une réponse possible unique, incluant le code de réponse et sa description.

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 – Définit un ensemble de réponses possibles pour la méthode, y compris les codes d'état et les descriptions.

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

Projet

Un lien vers le projet est également fourni au cas où quelque chose ne fonctionnerait pas ou si vous souhaitez l'examiner plus en détail :

Résumé

Swagger permet la génération automatique d'une documentation détaillée pour votre API, ce qui la rend plus facile à utiliser et à tester.

Tout était clair ?

Merci pour vos commentaires !

Section 3. Chapitre 7

Test des API RESTful

Démarrage avec Swagger

Utilisation des annotations

Projet

Résumé

Awesome!

Test des API RESTful

Démarrage avec Swagger

Utilisation des annotations

Projet

Résumé