Testen von RESTful API

Im vorherigen Kapitel wurden wir in Swagger eingeführt und wie man damit arbeitet. In diesem Kapitel werden wir seine Nutzung durch ein praktisches Beispiel erkunden und unsere erste REST API vollständig abschließen!

Einstieg in Swagger

Im Video wurden Sie in die Hauptschnittstelle von Swagger eingeführt und wie man mit ihr interagiert.

Für Methoden, die einen Request-Body akzeptieren, generiert Swagger automatisch JSON basierend auf dem Objekt, das der aktuelle Endpunkt erhält.

Zusätzlich, wenn Sie Parameter in der URL haben, können Sie diese einfach in den entsprechenden Feldern angeben.

Swagger zeigt auch die möglichen Statuscodes für den Endpunkt und gibt den Rückgabetyp des Objekts (JSON/XML) an.

Und am wichtigsten—Sie mussten keinen zusätzlichen Code schreiben, um diese Dokumentation zu erstellen!

Einfach das Hinzufügen der Abhängigkeit und das Konfigurieren bei Bedarf (obwohl oft keine Konfiguration erforderlich ist) reicht aus, um automatisch eine Dokumentation für Ihre REST-API zu erhalten!

Arbeiten mit Anmerkungen

Lassen Sie uns kurz die Annotationen überprüfen, die in diesem Kapitel behandelt wurden:

@Tag – Gruppiert verwandte Endpunkte und fügt ihnen eine Beschreibung hinzu.

BookController


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

@Operation – Beschreibt eine spezifische API-Methode, einschließlich ihres Zwecks und einer kurzen Beschreibung.

BookController


              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 – Beschreibt die Methodenparameter, wie Pfadvariablen, Abfrageparameter und so weiter.

BookController


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

@ApiResponse – Beschreibt eine einzelne spezifische mögliche Antwort, einschließlich des Antwortcodes und seiner Beschreibung.

BookController


              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 – Definiert eine Reihe von möglichen Antworten für die Methode, einschließlich Statuscodes und Beschreibungen.

BookController


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

Projekt

Ich stelle auch einen Link zum Projekt bereit, falls etwas nicht funktioniert oder wenn Sie es genauer erkunden möchten:

Zusammenfassung

Swagger ermöglicht die automatische Erstellung von detaillierter Dokumentation für Ihre API, was die Nutzung und Tests erleichtert.

Mit Annotationen wie @Operation, @ApiResponse und @Parameter können Sie das Verhalten von Methoden, Parametern und möglichen Antworten beschreiben, ohne zusätzlichen Code hinzuzufügen. Dies macht Ihre REST API klarer und für Entwickler zugänglicher.

War alles klar?

Danke für Ihr Feedback!

Abschnitt 3. Kapitel 7