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.

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

@Parameter – Beskriver metodeparametre, såsom sti-variabler, forespørgselsparametre osv.

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

@ApiResponses – Definerer et sæt af mulige svar for metoden, inklusive statuskoder og beskrivelser.

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.