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.

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

@Parameter – Kuvaa metodiparametrit, kuten polkumuuttujat, kyselyparametrit (query parameters) ja muut vastaavat.

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

@ApiResponses – Määrittelee joukon mahdollisia vastauksia metodille, mukaan lukien tilakoodit ja kuvaukset.

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.