Edellisessä luvussa tutustuimme Swagger ja sen käyttöön. Tässä luvussa tarkastelemme sen käyttöä käytännön esimerkin avulla ja viimeistelemme ensimmäisen REST API:mme!

Swaggerin käytön aloittaminen

Videolla esiteltiin Swaggerin pääkäyttöliittymä ja sen käyttö.

Menetelmille, jotka vastaanottavat pyyntöruumiin, Swagger generoi automaattisesti JSON-muotoisen datan sen objektin perusteella, jonka kyseinen päätepiste vastaanottaa.

Lisäksi, jos URL-osoitteessa on parametreja, voit helposti määrittää ne vastaaviin kenttiin.

Swagger näyttää myös mahdolliset tilakoodit kyseiselle päätepisteelle ja ilmoittaa olion palautustyypin (JSON/XML).

Ja mikä tärkeintä—sinun ei tarvinnut kirjoittaa yhtään ylimääräistä koodia tämän dokumentaation luomiseen!

Pelkkä riippuvuuden lisääminen ja tarvittaessa konfigurointi (vaikka usein konfigurointia ei tarvita) riittää, jotta saat automaattisesti dokumentaation REST API:llesi!

Työskentely annotaatioiden kanssa

Kerrataan lyhyesti tässä luvussa käsitellyt annotaatiot:

@Tag – Ryhmittelee liittyvät päätepisteet ja lisää niille kuvauksen.

BookController.java


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

@Operation – Kuvaa tietyn API-menetelmän, mukaan lukien sen tarkoitus ja lyhyt kuvaus.

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 – Kuvaa metodiparametrit, kuten polkumuuttujat, kyselyparametrit (query parameters) ja muut vastaavat.

BookController.java


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

@ApiResponse – Kuvaa yksittäisen mahdollisen vastauksen, mukaan lukien vastauskoodi ja sen kuvaus.

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 – Määrittelee joukon mahdollisia vastauksia metodille, mukaan lukien tilakoodit ja kuvaukset.

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

Projekti

Tarjoan myös linkin projektiin siltä varalta, että jokin ei toimi tai jos haluat tutustua siihen tarkemmin:

Yhteenveto

Swagger mahdollistaa yksityiskohtaisen dokumentaation automaattisen luomisen API:lle, mikä tekee siitä helpommin käytettävän ja testattavan.

Annotaatioiden kuten @Operation, @ApiResponse ja @Parameter avulla voit kuvata metodien, parametrien ja mahdollisten vastausten toimintaa ilman ylimääräistä koodia. Tämä selkeyttää REST API:a ja tekee siitä helpommin lähestyttävän kehittäjille.

Oliko kaikki selvää?

Kiitos palautteestasi!

Osio 3. Luku 7

Kysy tekoälyä

Kysy mitä tahansa tai kokeile jotakin ehdotetuista kysymyksistä aloittaaksesi keskustelumme

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

Pyyhkäise näyttääksesi valikon

Edellisessä luvussa tutustuimme Swagger ja sen käyttöön. Tässä luvussa tarkastelemme sen käyttöä käytännön esimerkin avulla ja viimeistelemme ensimmäisen REST API:mme!

Swaggerin käytön aloittaminen

Videolla esiteltiin Swaggerin pääkäyttöliittymä ja sen käyttö.

Menetelmille, jotka vastaanottavat pyyntöruumiin, Swagger generoi automaattisesti JSON-muotoisen datan sen objektin perusteella, jonka kyseinen päätepiste vastaanottaa.

Lisäksi, jos URL-osoitteessa on parametreja, voit helposti määrittää ne vastaaviin kenttiin.

Swagger näyttää myös mahdolliset tilakoodit kyseiselle päätepisteelle ja ilmoittaa olion palautustyypin (JSON/XML).

Ja mikä tärkeintä—sinun ei tarvinnut kirjoittaa yhtään ylimääräistä koodia tämän dokumentaation luomiseen!

Pelkkä riippuvuuden lisääminen ja tarvittaessa konfigurointi (vaikka usein konfigurointia ei tarvita) riittää, jotta saat automaattisesti dokumentaation REST API:llesi!

Työskentely annotaatioiden kanssa

Kerrataan lyhyesti tässä luvussa käsitellyt annotaatiot:

@Tag – Ryhmittelee liittyvät päätepisteet ja lisää niille kuvauksen.

BookController.java


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

@Operation – Kuvaa tietyn API-menetelmän, mukaan lukien sen tarkoitus ja lyhyt kuvaus.

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 – Kuvaa metodiparametrit, kuten polkumuuttujat, kyselyparametrit (query parameters) ja muut vastaavat.

BookController.java


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

@ApiResponse – Kuvaa yksittäisen mahdollisen vastauksen, mukaan lukien vastauskoodi ja sen kuvaus.

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 – Määrittelee joukon mahdollisia vastauksia metodille, mukaan lukien tilakoodit ja kuvaukset.

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

Projekti

Tarjoan myös linkin projektiin siltä varalta, että jokin ei toimi tai jos haluat tutustua siihen tarkemmin:

Yhteenveto

Swagger mahdollistaa yksityiskohtaisen dokumentaation automaattisen luomisen API:lle, mikä tekee siitä helpommin käytettävän ja testattavan.

Oliko kaikki selvää?

Kiitos palautteestasi!

Osio 3. Luku 7

RESTful API:n Testaaminen

Swaggerin käytön aloittaminen

Työskentely annotaatioiden kanssa

Projekti

Yhteenveto

Awesome!

RESTful API:n Testaaminen

Swaggerin käytön aloittaminen

Työskentely annotaatioiden kanssa

Projekti

Yhteenveto