I det forrige kapitel blev vi introduceret til Swagger og hvordan man arbejder med det. I dette kapitel vil vi udforske dets anvendelse gennem et praktisk eksempel og fuldføre vores første REST API!

Kom godt i gang med Swagger

I videoen blev du introduceret til Swagger's hovedgrænseflade og hvordan man interagerer med den.

For metoder, der accepterer en request body, genererer Swagger automatisk JSON baseret på det objekt, som det aktuelle endpoint modtager.

Derudover, hvis der er parametre i URL'en, kan de nemt angives i de tilsvarende felter.

Swagger viser også de mulige statuskoder for endpointet og angiver returtypen for objektet (JSON/XML).

Og vigtigst af alt—det var ikke nødvendigt at skrive yderligere kode for at generere denne dokumentation!

Det er tilstrækkeligt blot at tilføje afhængigheden og konfigurere den om nødvendigt (selvom der ofte ikke kræves nogen konfiguration) for automatisk at få dokumentation til din REST API!

Arbejde med annoteringer

Lad os kort gennemgå de annoteringer, der er dækket i dette kapitel:

@Tag – Grupperer relaterede endpoints og tilføjer en beskrivelse til dem.

BookController.java


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

@Operation – Beskriver en specifik API-metode, herunder dens formål og en kort beskrivelse.

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 – Beskriver metodeparametre, såsom sti-variabler, forespørgselsparametre osv.

BookController.java


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

@ApiResponse – Beskriver et enkelt specifikt muligt svar, inklusive svarkode og dens beskrivelse.

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 – Definerer et sæt af mulige svar for metoden, inklusive statuskoder og beskrivelser.

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

Der gives også et link til projektet i tilfælde af, at noget ikke fungerer, eller hvis du ønsker at udforske det nærmere:

Resumé

Swagger muliggør automatisk generering af detaljeret dokumentation for din API, hvilket gør det nemmere at anvende og teste.

Med annotationer som @Operation, @ApiResponse og @Parameter kan du beskrive adfærden for metoder, parametre og mulige svar uden at tilføje ekstra kode. Dette gør din REST API mere overskuelig og mere tilgængelig for udviklere.

Var alt klart?

Tak for dine kommentarer!

Sektion 3. Kapitel 7

Spørg AI

Spørg om hvad som helst eller prøv et af de foreslåede spørgsmål for at starte vores chat

Awesome!

Completion rate improved to 3.45

Stryg for at vise menuen

Kom godt i gang med Swagger

I videoen blev du introduceret til Swagger's hovedgrænseflade og hvordan man interagerer med den.

For metoder, der accepterer en request body, genererer Swagger automatisk JSON baseret på det objekt, som det aktuelle endpoint modtager.

Derudover, hvis der er parametre i URL'en, kan de nemt angives i de tilsvarende felter.

Swagger viser også de mulige statuskoder for endpointet og angiver returtypen for objektet (JSON/XML).

Og vigtigst af alt—det var ikke nødvendigt at skrive yderligere kode for at generere denne dokumentation!

Arbejde med annoteringer

Lad os kort gennemgå de annoteringer, der er dækket i dette kapitel:

@Tag – Grupperer relaterede endpoints og tilføjer en beskrivelse til dem.

BookController.java


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

@Operation – Beskriver en specifik API-metode, herunder dens formål og en kort beskrivelse.

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 – Beskriver metodeparametre, såsom sti-variabler, forespørgselsparametre osv.

BookController.java


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

@ApiResponse – Beskriver et enkelt specifikt muligt svar, inklusive svarkode og dens beskrivelse.

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 – Definerer et sæt af mulige svar for metoden, inklusive statuskoder og beskrivelser.

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

Der gives også et link til projektet i tilfælde af, at noget ikke fungerer, eller hvis du ønsker at udforske det nærmere:

Resumé

Swagger muliggør automatisk generering af detaljeret dokumentation for din API, hvilket gør det nemmere at anvende og teste.

Var alt klart?

Tak for dine kommentarer!

Sektion 3. Kapitel 7

Test af RESTful API

Kom godt i gang med Swagger

Arbejde med annoteringer

Projekt

Resumé

Awesome!

Test af RESTful API

Kom godt i gang med Swagger

Arbejde med annoteringer

Projekt

Resumé