I forrige kapittel ble vi introdusert for Swagger og hvordan man arbeider med det. I dette kapitlet skal vi utforske bruken gjennom et praktisk eksempel og fullføre vår første REST API!

Komme i gang med Swagger

I videoen ble du introdusert for hovedgrensesnittet til Swagger og hvordan man interagerer med det.

For metoder som aksepterer en forespørselskropp, genererer Swagger automatisk JSON basert på objektet som gjeldende endepunkt mottar.

I tillegg, hvis du har parametere i URL-en, kan du enkelt angi dem i de tilsvarende feltene.

Swagger viser også mulige statuskoder for endepunktet og angir returtypen til objektet (JSON/XML).

Og viktigst av alt—du trengte ikke å skrive noen ekstra kode for å generere denne dokumentasjonen!

Det er nok å legge til avhengigheten og konfigurere den om nødvendig (selv om det ofte ikke er nødvendig med konfigurasjon) for å automatisk få dokumentasjon for din REST API!

Arbeide med annotasjoner

La oss kort gjennomgå annotasjonene som er dekket i dette kapittelet:

@Tag – Grupperer relaterte endepunkter og legger til en beskrivelse til dem.

BookController.java


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

@Operation – Beskriver en spesifikk API-metode, inkludert 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 metodeparametere, som sti-variabler, spørringsparametere og lignende.

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 en enkelt spesifikk mulig respons, inkludert responskode 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 sett med mulige responser for metoden, inkludert 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);
}

Prosjekt

Jeg legger også ved en lenke til prosjektet i tilfelle noe ikke fungerer eller hvis du ønsker å utforske det nærmere:

Sammendrag

Swagger muliggjør automatisk generering av detaljert dokumentasjon for din API, noe som gjør den enklere å bruke og teste.

Med annotasjoner som @Operation, @ApiResponse og @Parameter kan du beskrive oppførselen til metoder, parametere og mulige responser uten å legge til ekstra kode. Dette gjør din REST API tydeligere og mer tilgjengelig for utviklere.

Alt var klart?

Takk for tilbakemeldingene dine!

Seksjon 3. Kapittel 7

Spør AI

Spør om hva du vil, eller prøv ett av de foreslåtte spørsmålene for å starte chatten vår

Awesome!

Completion rate improved to 3.45

Sveip for å vise menyen

Komme i gang med Swagger

I videoen ble du introdusert for hovedgrensesnittet til Swagger og hvordan man interagerer med det.

For metoder som aksepterer en forespørselskropp, genererer Swagger automatisk JSON basert på objektet som gjeldende endepunkt mottar.

I tillegg, hvis du har parametere i URL-en, kan du enkelt angi dem i de tilsvarende feltene.

Swagger viser også mulige statuskoder for endepunktet og angir returtypen til objektet (JSON/XML).

Og viktigst av alt—du trengte ikke å skrive noen ekstra kode for å generere denne dokumentasjonen!

Arbeide med annotasjoner

La oss kort gjennomgå annotasjonene som er dekket i dette kapittelet:

@Tag – Grupperer relaterte endepunkter og legger til en beskrivelse til dem.

BookController.java


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

@Operation – Beskriver en spesifikk API-metode, inkludert 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 metodeparametere, som sti-variabler, spørringsparametere og lignende.

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 en enkelt spesifikk mulig respons, inkludert responskode 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 sett med mulige responser for metoden, inkludert 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);
}

Prosjekt

Jeg legger også ved en lenke til prosjektet i tilfelle noe ikke fungerer eller hvis du ønsker å utforske det nærmere:

Sammendrag

Swagger muliggjør automatisk generering av detaljert dokumentasjon for din API, noe som gjør den enklere å bruke og teste.

Alt var klart?

Takk for tilbakemeldingene dine!

Seksjon 3. Kapittel 7

Testing av RESTful API

Komme i gang med Swagger

Arbeide med annotasjoner

Prosjekt

Sammendrag

Awesome!

Testing av RESTful API

Komme i gang med Swagger

Arbeide med annotasjoner

Prosjekt

Sammendrag