I föregående kapitel introducerades vi till Swagger och hur man arbetar med det. I detta kapitel kommer vi att utforska dess användning genom ett praktiskt exempel och slutföra vårt första REST API!

Kom igång med Swagger

I videon introducerades du till Swagger's huvudgränssnitt och hur man interagerar med det.

För metoder som accepterar en request body genererar Swagger automatiskt JSON baserat på det objekt som nuvarande endpoint tar emot.

Dessutom, om du har parametrar i URL:en, kan du enkelt ange dem i de motsvarande fälten.

Swagger visar också möjliga statuskoder för endpointen och specificerar returtypen för objektet (JSON/XML).

Och viktigast av allt—du behövde inte skriva någon ytterligare kod för att generera denna dokumentation!

Att helt enkelt lägga till beroendet och konfigurera det vid behov (även om konfiguration ofta inte krävs) räcker för att automatiskt få dokumentation för din REST API!

Arbeta med annoteringar

En kort översikt av annoteringarna som behandlas i detta kapitel:

@Tag – Grupperar relaterade endpoints och lägger till en beskrivning till dem.

BookController.java


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

@Operation – Beskriver en specifik API-metod, inklusive dess syfte och en kort beskrivning.

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 metodparametrar, såsom sökvägsvariabler, frågeparametrar och liknande.

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 ett enskilt specifikt möjligt svar, inklusive svarskod och dess beskrivning.

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 – Definierar en uppsättning av möjliga svar för metoden, inklusive statuskoder och beskrivningar.

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

Jag tillhandahåller även en länk till projektet ifall något inte fungerar eller om du vill utforska det mer i detalj:

Sammanfattning

Swagger möjliggör automatisk generering av detaljerad dokumentation för din API, vilket gör den enklare att använda och testa.

Med annoteringar som @Operation, @ApiResponse och @Parameter kan du beskriva beteendet hos metoder, parametrar och möjliga svar utan att lägga till extra kod. Detta gör din REST API tydligare och mer tillgänglig för utvecklare.

Var allt tydligt?

Tack för dina kommentarer!

Avsnitt 3. Kapitel 7

Fråga AI

Fråga vad du vill eller prova någon av de föreslagna frågorna för att starta vårt samtal

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

Svep för att visa menyn

Kom igång med Swagger

I videon introducerades du till Swagger's huvudgränssnitt och hur man interagerar med det.

För metoder som accepterar en request body genererar Swagger automatiskt JSON baserat på det objekt som nuvarande endpoint tar emot.

Dessutom, om du har parametrar i URL:en, kan du enkelt ange dem i de motsvarande fälten.

Swagger visar också möjliga statuskoder för endpointen och specificerar returtypen för objektet (JSON/XML).

Och viktigast av allt—du behövde inte skriva någon ytterligare kod för att generera denna dokumentation!

Att helt enkelt lägga till beroendet och konfigurera det vid behov (även om konfiguration ofta inte krävs) räcker för att automatiskt få dokumentation för din REST API!

Arbeta med annoteringar

En kort översikt av annoteringarna som behandlas i detta kapitel:

@Tag – Grupperar relaterade endpoints och lägger till en beskrivning till dem.

BookController.java


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

@Operation – Beskriver en specifik API-metod, inklusive dess syfte och en kort beskrivning.

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 metodparametrar, såsom sökvägsvariabler, frågeparametrar och liknande.

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 ett enskilt specifikt möjligt svar, inklusive svarskod och dess beskrivning.

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 – Definierar en uppsättning av möjliga svar för metoden, inklusive statuskoder och beskrivningar.

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

Jag tillhandahåller även en länk till projektet ifall något inte fungerar eller om du vill utforska det mer i detalj:

Sammanfattning

Swagger möjliggör automatisk generering av detaljerad dokumentation för din API, vilket gör den enklare att använda och testa.

Var allt tydligt?

Tack för dina kommentarer!

Avsnitt 3. Kapitel 7

Testning av RESTful API

Kom igång med Swagger

Arbeta med annoteringar

Projekt

Sammanfattning

Awesome!

Testning av RESTful API

Kom igång med Swagger

Arbeta med annoteringar

Projekt

Sammanfattning