In het vorige hoofdstuk maakten we kennis met Swagger en hoe hiermee te werken. In dit hoofdstuk verkennen we het gebruik aan de hand van een praktisch voorbeeld en voltooien we onze eerste REST API volledig!

Aan de slag met Swagger

In de video werd u geïntroduceerd tot de hoofdinterface van Swagger en hoe hiermee te werken.

Voor methoden die een request body accepteren, genereert Swagger automatisch JSON op basis van het object dat het huidige endpoint ontvangt.

Bovendien, als er parameters in de URL staan, kunnen deze eenvoudig worden opgegeven in de overeenkomende velden.

Swagger toont ook de mogelijke statuscodes voor het endpoint en specificeert het returntype van het object (JSON/XML).

En het belangrijkste—er hoefde geen extra code te worden geschreven om deze documentatie te genereren!

Het toevoegen van de dependency en het configureren ervan indien nodig (hoewel vaak geen configuratie vereist is) is voldoende om automatisch documentatie voor de REST API te verkrijgen!

Werken met annotaties

Hier volgt een kort overzicht van de annotaties die in dit hoofdstuk aan bod komen:

@Tag – Groepeert gerelateerde endpoints en voegt daar een beschrijving aan toe.

BookController.java


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

@Operation – Beschrijft een specifieke API-methode, inclusief het doel en een korte omschrijving.

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 – Beschrijft de methodeparameters, zoals padvariabelen, queryparameters, enzovoort.

BookController.java


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

@ApiResponse – Beschrijft een enkele specifieke mogelijke respons, inclusief de responscode en de beschrijving daarvan.

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 – Definieert een set van mogelijke antwoorden voor de methode, inclusief statuscodes en beschrijvingen.

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

Project

Er is ook een link naar het project beschikbaar voor het geval er iets niet werkt of als je het in meer detail wilt bekijken:

Samenvatting

Swagger maakt de automatische generatie van gedetailleerde documentatie voor je API mogelijk, waardoor het makkelijker wordt om deze te gebruiken en te testen.

Met annotaties zoals @Operation, @ApiResponse en @Parameter kun je het gedrag van methoden, parameters en mogelijke responses beschrijven zonder extra code toe te voegen. Dit maakt je REST API duidelijker en beter toegankelijk voor ontwikkelaars.

Was alles duidelijk?

Bedankt voor je feedback!

Sectie 3. Hoofdstuk 7

Vraag AI

Vraag wat u wilt of probeer een van de voorgestelde vragen om onze chat te starten.

Awesome!

Completion rate improved to 3.45

Veeg om het menu te tonen

Aan de slag met Swagger

In de video werd u geïntroduceerd tot de hoofdinterface van Swagger en hoe hiermee te werken.

Voor methoden die een request body accepteren, genereert Swagger automatisch JSON op basis van het object dat het huidige endpoint ontvangt.

Bovendien, als er parameters in de URL staan, kunnen deze eenvoudig worden opgegeven in de overeenkomende velden.

Swagger toont ook de mogelijke statuscodes voor het endpoint en specificeert het returntype van het object (JSON/XML).

En het belangrijkste—er hoefde geen extra code te worden geschreven om deze documentatie te genereren!

Werken met annotaties

Hier volgt een kort overzicht van de annotaties die in dit hoofdstuk aan bod komen:

@Tag – Groepeert gerelateerde endpoints en voegt daar een beschrijving aan toe.

BookController.java


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

@Operation – Beschrijft een specifieke API-methode, inclusief het doel en een korte omschrijving.

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 – Beschrijft de methodeparameters, zoals padvariabelen, queryparameters, enzovoort.

BookController.java


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

@ApiResponse – Beschrijft een enkele specifieke mogelijke respons, inclusief de responscode en de beschrijving daarvan.

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 – Definieert een set van mogelijke antwoorden voor de methode, inclusief statuscodes en beschrijvingen.

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

Project

Er is ook een link naar het project beschikbaar voor het geval er iets niet werkt of als je het in meer detail wilt bekijken:

Samenvatting

Swagger maakt de automatische generatie van gedetailleerde documentatie voor je API mogelijk, waardoor het makkelijker wordt om deze te gebruiken en te testen.

Was alles duidelijk?

Bedankt voor je feedback!

Sectie 3. Hoofdstuk 7

Testen van Restful API

Aan de slag met Swagger

Werken met annotaties

Project

Samenvatting

Awesome!

Testen van Restful API

Aan de slag met Swagger

Werken met annotaties

Project

Samenvatting