Im vorherigen Kapitel wurden wir in Swagger eingeführt und haben gelernt, damit zu arbeiten. In diesem Kapitel werden wir die Anwendung anhand eines praktischen Beispiels untersuchen und unsere erste REST-API vollständig abschließen!

Einstieg in Swagger

Im Video wurden Sie mit der Hauptoberfläche von Swagger und der Interaktion damit vertraut gemacht.

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

Zusätzlich können Sie, falls Parameter in der URL vorhanden sind, diese einfach in den entsprechenden Feldern angeben.

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

Und am wichtigsten—es war nicht notwendig, zusätzlichen Code zu schreiben, um diese Dokumentation zu erzeugen!

Das Hinzufügen der Abhängigkeit und ggf. deren Konfiguration (wobei oft keine Konfiguration erforderlich ist) reicht aus, um automatisch eine Dokumentation für Ihre REST API zu erhalten!

Arbeiten mit Annotationen

Kurze Übersicht über die Annotationen, die in diesem Kapitel behandelt wurden:

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

BookController.java


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

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

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

BookController.java


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

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

Projekt

Ein Link zum Projekt wird ebenfalls bereitgestellt, falls etwas nicht funktioniert oder wenn Sie es detaillierter erkunden möchten:

Zusammenfassung

Swagger ermöglicht die automatische Generierung einer ausführlichen Dokumentation für Ihre API, was die Nutzung und das Testen 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 zu schreiben. Dadurch wird Ihre REST API verständlicher und für Entwickler zugänglicher.

War alles klar?

Danke für Ihr Feedback!

Abschnitt 3. Kapitel 7

Fragen Sie AI

Fragen Sie alles oder probieren Sie eine der vorgeschlagenen Fragen, um unser Gespräch zu beginnen

Suggested prompts:

Can you explain more about how to use Swagger annotations in my own project?

What are some best practices for writing clear API documentation with Swagger?

How do I handle custom error responses in Swagger documentation?

Awesome!

Completion rate improved to 3.45

Swipe um das Menü anzuzeigen

Einstieg in Swagger

Im Video wurden Sie mit der Hauptoberfläche von Swagger und der Interaktion damit vertraut gemacht.

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

Zusätzlich können Sie, falls Parameter in der URL vorhanden sind, diese einfach in den entsprechenden Feldern angeben.

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

Und am wichtigsten—es war nicht notwendig, zusätzlichen Code zu schreiben, um diese Dokumentation zu erzeugen!

Arbeiten mit Annotationen

Kurze Übersicht über die Annotationen, die in diesem Kapitel behandelt wurden:

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

BookController.java


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

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

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

BookController.java


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

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

Projekt

Ein Link zum Projekt wird ebenfalls bereitgestellt, falls etwas nicht funktioniert oder wenn Sie es detaillierter erkunden möchten:

Zusammenfassung

Swagger ermöglicht die automatische Generierung einer ausführlichen Dokumentation für Ihre API, was die Nutzung und das Testen erleichtert.

War alles klar?

Danke für Ihr Feedback!

Abschnitt 3. Kapitel 7

Testen von RESTful API

Einstieg in Swagger

Arbeiten mit Annotationen

Projekt

Zusammenfassung

Awesome!

Testen von RESTful API

Einstieg in Swagger

Arbeiten mit Annotationen

Projekt

Zusammenfassung