streamalism.org

Jeg kunngjorde nettopp det nye Lær våren kurs, med fokus på det grunnleggende i vår 5 og vårstøvel 2:

1. Oversikt

Dokumentasjon er en viktig del av å bygge REST APIer. I denne veiledningen tar vi en titt på SpringDoc - et verktøy som forenkler generering og vedlikehold av API-dokumenter, basert på OpenAPI 3-spesifikasjonen, for Spring Boot 1.x og 2.x-applikasjoner.

2. Sette opp springdoc-openapi

For å la springdoc-openapi automatisk generere OpenAPI 3-spesifikasjonsdokumentene for API-et vårt, legger vi ganske enkelt til springdoc-openapi-ui avhengighet til vår pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

Når vi kjører applikasjonen vår, vil OpenAPI-beskrivelsene være tilgjengelige på banen / v3 / api-docs som standard - for eksempel:

// localhost: 8080 / v3 / api-docs /

For å bruke en tilpasset bane kan vi indikere i application.properties fil:

springdoc.api-docs.path = / api-docs

Nå får vi tilgang til dokumentene på:

// localhost: 8080 / api-docs /

OpenAPI-definisjonene er i JSONformat som standard. Til yaml format, kan vi få definisjonene på:

//localhost:8080/api-docs.yaml

3. Sette opp springdoc-openapi Med Swagger UI

I tillegg til å generere OpenAPI 3-spesifikasjonen, kan vi integrere springdoc-openapi med Swagger UI slik at vi kan samhandle med API-spesifikasjonen vår og utøve endepunktene.

3.1. Maven avhengighet

Alt vi trenger å gjøre for å sette opp springdoc-openapi med Swagger UI er å legge til avhengigheten springdoc-openapi-ui til prosjektets pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

Vi kan nå få tilgang til API-dokumentasjonen på:

//localhost:8080/swagger-ui.html

3.2. Støtte for swagger-ui Eiendommer

Springdoc-openapi støtter også swagger-ui-egenskaper. Disse kan brukes som Spring Boot-egenskaper, med prefikset springdoc.swagger-ui.

La oss for eksempel tilpasse banen til API-dokumentasjonen vår. Vi kan gjøre dette ved å endre vår application.properties å inkludere:

springdoc.swagger-ui.path = / swagger-ui-custom.html

Så nå vil API-dokumentasjonen vår være tilgjengelig på //localhost:8080/swagger-ui-custom.html.

For å sortere API-stiene i rekkefølge etter HTTP-metodene, kan vi legge til:

springdoc.swagger-ui.operationsSorter = metode

3.3. Eksempel på API

Anta at applikasjonen vår har en kontroller for administrasjon Boks:

@RestController @RequestMapping ("/ api / book") public class BookController {@Autowired private BookRepository repository; @GetMapping ("/ {id}") public Book findById (@PathVariable long id) {return repository.findById (id) .orElseThrow (() -> new BookNotFoundException ()); } @GetMapping ("/") offentlig samling findBooks () {return repository.getBooks (); } @PutMapping ("/ {id}") @ResponseStatus (HttpStatus.OK) offentlig bokoppdateringsbok (@PathVariable ("id") endelig streng-id, @RequestBody endelig bokbok) {returbok; }} 

Når vi kjører applikasjonen vår, kan vi se dokumentasjonen på:

//localhost:8080/swagger-ui-custom.html

La oss bore ned til / api / bok sluttpunkt og se detaljene for forespørsel og svar:

4. Integrering av springdoc-openapi med Spring WebFlux

Vi kan integrere springdoc-openapi og Swagger UI i et Spring WebFlux-prosjekt ved å legge til springdoc-openapi-webflux-ui:

 org.springdoc springdoc-openapi-webflux-ui 1.5.2 

Og som før vil dokumentene være tilgjengelige på:

//localhost:8080/swagger-ui.html

For å tilpasse banen, kan vi igjen legge til springdoc.swagger-ui.path eiendom i vår application.properties.

5. Å avsløre informasjon om paginering

Spring Data JPA integreres ganske enkelt med Spring MVC. Et eksempel på slike integrasjoner er Sidelig Brukerstøtte:

@GetMapping ("/ filter") offentlige sidefilterBøker (side-side) {return repository.getBooks (side-side); }

Først kan vi forvente at SpringDoc vil legge til side, størrelse, og sortere spørreparametere til den genererte dokumentasjonen. Imidlertid oppfyller SpringDoc som standard ikke denne forventningen. For å låse opp denne funksjonen, bør vi legge til springdoc-openapi-data-rest avhengighet:

 org.springdoc springdoc-openapi-data-rest 1.5.2 

Nå legger den de forventede spørringsparametrene til dokumentasjonen:

6. Bruke springdoc-openapi Maven Plugin

Springdoc-openapi-biblioteket tilbyr et Maven-plugin springdoc-openapi-maven-plugin for å generere OpenAPI-beskrivelser i json og yaml formater.

De springdoc-openapi-maven-plugin plugin fungerer med spring-boot-maven plugg inn. Maven driver openapi plugin under integrasjonstest fase.

La oss se hvordan vi kan konfigurere plugin-modulen i vår pom.xml:

 org.springframework.boot spring-boot-maven-plugin 2.3.3.RELEASE pre-integration-test start post-integration-test stop org.springdoc springdoc-openapi-maven-plugin 0.2 integration-test generere 

Vi kan også konfigurere programtillegget til å bruke tilpassede verdier:

  ......... // localhost: 8080 / v3 / api-docs openapi.json $ {project.build.directory} 

La oss se nærmere på parametrene vi kan konfigurere for programtillegget:

• apiDocsUrl - URL der dokumentene er tilgjengelige i JSON-format, med standardinnstillingen // localhost: 8080 / v3 / api-docs
• outputFileName - Navnet på filen der definisjonene er lagret, er som standard openapi.json
• outputDir - Absolutt bane for katalogen der dokumentene er lagret - som standard, $ {project.build.directory}

7. Automatisk generering av dokumenter ved bruk av JSR-303 Bean Validation

Når modellen vår inkluderer JSR-303 beanvalideringsanmerkninger, for eksempel @Ikke null, @NotBlank, @Størrelse, @Min, og @Max, springdoc-openapi-biblioteket bruker dem til å generere ytterligere skjemadokumentasjon for de tilsvarende begrensningene.

La oss se et eksempel med vår Bok bønne:

public class Book {privat lang id; @NotBlank @Size (min = 0, max = 20) privat strengetittel; @NotBlank @Size (min = 0, max = 30) privat strengforfatter; }

Nå er dokumentasjonen generert for Bok bønne er litt mer informativ:

8. Generer dokumentasjon ved hjelp av @ControllerAdvice og @ResponseStatus

Ved hjelp av @ResponseStatus om metoder i a @RestControllerAdvice klasse genererer automatisk dokumentasjon for responskodene. I dette @RestControllerAdvice klasse, er de to metodene merket med @ResponseStatus:

@RestControllerAdvice offentlig klasse GlobalControllerExceptionHandler {@ExceptionHandler (ConversionFailedException.class) @ResponseStatus (HttpStatus.BAD_REQUEST) public ResponseEntity handleConnversion (RuntimeException ex) {return new ResponseEntity (ex.getBess_Start); } @ExceptionHandler (BookNotFoundException.class) @ResponseStatus (HttpStatus.NOT_FOUND) public ResponseEntity handleBookNotFound (RuntimeException ex) {return new ResponseEntity (ex.getMessage (), HttpStatus.NOT_FOUND); }}

Som et resultat kan vi nå se dokumentasjonen for svarkodene 400 og 404:

9. Generer dokumentasjon ved hjelp av @Operasjon og @ApiResponses

La oss deretter se hvordan vi kan legge til en beskrivelse i API-et vårt ved hjelp av et par OpenAPI-spesifikke merknader.

For å gjøre det, vil vi kommentere kontrolleren vår / api / book / {id} sluttpunkt med @Operasjon og @ApiResponses:

@Operation (summary = "Få en bok etter id") @ApiResponses (verdi = {@ApiResponse (responsCode = "200", beskrivelse = "Fant boken", content = {@Content (mediaType = "application / json") , skjema = @Schema (implementering = Book.class))}), @ApiResponse (responsCode = "400", beskrivelse = "Ugyldig ID levert", innhold = @Content), @ApiResponse (responsCode = "404", beskrivelse = "Bok ble ikke funnet", content = @Content)}) @GetMapping ("/ {id}") offentlig Book findById (@Parameter (beskrivelse = "id for bok som skal søkes") @ PathVariable lang id) {returregister. findById (id) .orElseThrow (() -> new BookNotFoundException ()); }

Og her er effekten:

Som vi kan se, teksten vi la til @Operasjon er plassert på API-operasjonsnivå. Tilsvarende er beskrivelsen lagt til forskjellige @ApiResponse elementer i @ApiResponses container kommentar er også synlig her, og gir mening til API-svarene våre.

Vi får tydeligvis ikke noe skjema for svarene 400 og 404 ovenfor. Fordi vi definerte en tom @Innhold for dem vises bare beskrivelsene deres.

10. Kotlin-støtte

Siden Spring Boot 2.x har førsteklasses støtte for Kotlin, støtter SpringDoc dette JVM-språket ut av esken for Boot 2.x-applikasjoner.

For å se dette i aksjon lager vi en enkel Foo API i Kotlin.

Etter det første oppsettet vil vi legge til en dataklasse og en kontroller. Vi legger dem til i en underpakke av Boot-appen vår, slik at når den kjøres, velger den vår FooController opp sammen med det tidligere BookController:

@Entity dataklasse Foo (@Id val id: Long = 0, @NotBlank @Size (min = 0, max = 50) val name: String = "") @RestController @RequestMapping ("/") class FooController () { val fooList: List = listOf (Foo (1, "one"), Foo (2, "two")) @Operation (summary = "Get all foos") @ApiResponses (value = [ApiResponse (responseCode = "200", beskrivelse = "Fant Foos", content = [(Content (mediaType = "application / json", array = (ArraySchema (schema = Schema (implementering = Foo :: klasse)))))), ApiResponse (responsCode = "400 ", beskrivelse =" Dårlig forespørsel ", content = [Content ()]), ApiResponse (responseCode =" 404 ", description =" Fant ikke Foos ", content = [Content ()])]) @GetMapping (" / foo ") moro getAllFoos (): Liste = fooList}

Nå når vi treffer vår API-dokumentasjons-URL, ser vi Foo API også:

For å forbedre støtten til Kotlin-typer, kan vi legge til denne avhengigheten:

 org.springdoc springdoc-openapi-kotlin

Etter det vil vårt Foo-skjema se mer informativt ut. På samme måte som det gjorde da vi hadde lagt til JSR-303 Bean Validation:

11. Konklusjon

I denne artikkelen lærte vi å sette opp springdoc-openapi i prosjektene våre. Så så vi hvordan vi kunne integrere springdoc-openapi med Swagger UI. Vi så også hvordan vi kan gjøre dette med Spring Webflux-prosjekter.

Deretter brukte vi springdoc-openapi Maven Plugin til å generere OpenAPI-definisjoner for API-ene våre, og vi så hvordan vi skulle eksponere personsøk- og sorteringsinformasjon fra Spring Data. Etter det så vi på hvordan springdoc-openapi genererer dokumentasjon automatisk ved hjelp av JSR 303-bønnevalideringsanmerkninger og @ResponseStatus merknader i @ControllerAdvice klasse.

Så lærte vi hvordan vi kan legge til en beskrivelse i API-et vårt ved hjelp av noen få OpenAPI-spesifikke merknader. Til slutt tok vi en titt på OpenAPIs støtte til Kotlin.

Springdoc-openapi genererer API-dokumentasjon i henhold til OpenAPI 3-spesifikasjonen. Videre håndterer den også Swagger UI-konfigurasjonen for oss, noe som gjør API-dokumentgenerering til en ganske enkel oppgave.

Som alltid er koden tilgjengelig på GitHub.

Jeg kunngjorde nettopp det nye Lær våren kurs, med fokus på det grunnleggende i vår 5 og vårstøvel 2: