streamalism.org

Jeg har lige annonceret det nye Lær foråret kursus med fokus på det grundlæggende i Spring 5 og Spring Boot 2:

1. Oversigt

Dokumentation er en vigtig del af opbygningen af ​​REST API'er. I denne vejledning ser vi på SpringDoc - et værktøj, der forenkler generering og vedligeholdelse af API-dokumenter, baseret på OpenAPI 3-specifikationen, til Spring Boot 1.x og 2.x applikationer.

2. Opsætning af springdoc-openapi

For at springdoc-openapi automatisk genererer OpenAPI 3-specifikationsdokumenterne til vores API, tilføjer vi simpelthen springdoc-openapi-ui afhængighed af vores pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

Derefter, når vi kører vores applikation, vil OpenAPI-beskrivelserne være tilgængelige på stien / v3 / api-docs som standard - for eksempel:

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

For at bruge en brugerdefineret sti kan vi angive i application.properties fil:

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

Nu kan vi få adgang til dokumenterne på:

// localhost: 8080 / api-docs /

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

//localhost:8080/api-docs.yaml

3. Opsætning af springdoc-openapi med Swagger UI

Udover at generere selve OpenAPI 3-specifikationen kan vi integrere springdoc-openapi med Swagger UI, så vi kan interagere med vores API-specifikation og udøve slutpunkterne.

3.1. Maven afhængighed

Alt, hvad vi skal gøre for at oprette springdoc-openapi med Swagger UI er at tilføje afhængighed springdoc-openapi-ui til projektets pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

Vi kan nu få adgang til API-dokumentationen på:

//localhost:8080/swagger-ui.html

3.2. Støtte for swagger-ui Ejendomme

Springdoc-openapi understøtter også swagger-ui egenskaber. Disse kan bruges som Spring Boot egenskaber med præfikset springdoc.swagger-ui.

Lad os for eksempel tilpasse stien til vores API-dokumentation. Vi kan gøre dette ved at ændre vores application.properties at inkludere:

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

Så nu vil vores API-dokumentation være tilgængelig på //localhost:8080/swagger-ui-custom.html.

For at sortere API-stierne i rækkefølge efter deres HTTP-metoder kan vi tilføje:

springdoc.swagger-ui.operationsSorter = metode

3.3. Eksempel på API

Antag, at vores ansøgning har en controller til styring Bestils:

@RestController @RequestMapping ("/ api / book") offentlig klasse BookController {@Autowired privat BookRepository-arkiv; @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 bogopdateringsbog (@PathVariable ("id") endelig streng-id, @RequestBody endelig bogbog) {returbog; }} 

Derefter, når vi kører vores applikation, kan vi se dokumentationen på:

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

Lad os bore ned til / api / bog slutpunkt og se detaljerne for dens anmodning og svar:

4. Integrering af springdoc-openapi med Spring WebFlux

Vi kan integrere springdoc-openapi og Swagger UI i et Spring WebFlux-projekt ved at tilføje springdoc-openapi-webflux-ui:

 org.springdoc springdoc-openapi-webflux-ui 1.5.2 

Og som før vil dokumenterne være tilgængelige på:

//localhost:8080/swagger-ui.html

For at tilpasse stien, her kunne vi igen tilføje springdoc.swagger-ui.sti ejendom i vores application.properties.

5. Eksponering af pagineringsinformation

Spring Data JPA integreres med Spring MVC ret problemfrit. Et eksempel på sådanne integrationer er Sidelig support:

@GetMapping ("/ filter") offentlige sider filterbøger (sideudsigtelig side) {return repository.getBooks (sideudsigt); }

Først kan vi forvente, at SpringDoc tilføjer side, størrelseog sortere forespørgselsparametre til den genererede dokumentation. Som standard opfylder SpringDoc imidlertid ikke denne forventning. For at låse op for denne funktion skal vi tilføje springdoc-openapi-data-rest afhængighed:

 org.springdoc springdoc-openapi-data-rest 1.5.2 

Nu tilføjer det de forventede forespørgselsparametre til dokumentationen:

6. Brug af springdoc-openapi Maven Plugin

Springdoc-openapi-biblioteket indeholder et Maven-plugin springdoc-openapi-maven-plugin til generering af OpenAPI-beskrivelser i json og yaml formater.

Det springdoc-openapi-maven-plugin plugin fungerer med spring-boot-maven plugin. Maven kører openapi plugin under integration-test fase.

Lad os se, hvordan vi kan konfigurere pluginet i vores 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 generer 

Vi kan også konfigurere pluginet til at bruge brugerdefinerede værdier:

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

Lad os se nærmere på de parametre, som vi kan konfigurere til pluginet:

• apiDocsUrl - URL, hvor dokumenterne kan fås i JSON-format med en standard på // localhost: 8080 / v3 / api-docs
• outputFileName - Navnet på den fil, hvor definitionerne er gemt, er som standard openapi.json
• outputDir - Absolut sti til det bibliotek, hvor dokumenterne er gemt - som standard $ {project.build.directory}

7. Automatisk dokumentgenerering ved hjælp af JSR-303 Bean Validation

Når vores model inkluderer JSR-303 beanvalideringsanmærkninger, såsom @NotNull, @NotBlank, @Størrelse, @Minog @Max, springdoc-openapi-biblioteket bruger dem til at generere yderligere skematisk dokumentation til de tilsvarende begrænsninger.

Lad os se et eksempel ved hjælp af vores Bestil bønne:

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

Nu er den genererede dokumentation til Bestil bønne er lidt mere informativ:

8. Generer dokumentation ved hjælp af @ControllerAdvice og @ResponseStatus

Ved brug af @ResponseStatus om metoder i a @RestControllerAdvice klasse genererer automatisk dokumentation for svarkoderne. Heri @RestControllerAdvice klasse, er de to metoder kommenteret med @ResponseStatus:

@RestControllerAdvice offentlig klasse GlobalControllerExceptionHandler {@ExceptionHandler (ConversionFailedException.class) @ResponseStatus (HttpStatus.BAD_REQUEST) public ResponseEntity handleConnversion (RuntimeException ex) {return new ResponseEntity (ex.getMess_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 nu se dokumentationen for svarkoderne 400 og 404:

9. Generer dokumentation ved hjælp af @Operation og @ApiResponses

Lad os derefter se, hvordan vi kan tilføje en beskrivelse til vores API ved hjælp af et par OpenAPI-specifikke kommentarer.

For at gøre det annoterer vi vores controller's / api / book / {id} slutpunkt med @Operation og @ApiResponses:

@Operation (summary = "Få en bog efter dens id") @ApiResponses (værdi = {@ApiResponse (responsCode = "200", beskrivelse = "Fundet bogen", content = {@Content (mediaType = "application / json") , skema = @Schema (implementering = Book.class))}), @ApiResponse (responsCode = "400", beskrivelse = "Ugyldig id leveret", indhold = @Content), @ApiResponse (responsCode = "404", beskrivelse = "Bog blev ikke fundet", indhold = @Content)}) @GetMapping ("/ {id}") offentlig Book findById (@Parameter (beskrivelse = "id for bog, der skal søges") @PathVariable lang id) {returlager. findById (id) .orElseThrow (() -> new BookNotFoundException ()); }

Og her er effekten:

Som vi kan se, teksten vi tilføjede til @Operation er placeret på API-driftsniveau. Ligeledes tilføjede beskrivelsen forskellige @ApiResponse elementer i @ApiResponses container annotation er også synlig her og tilføjer betydning til vores API-svar.

Vi får åbenbart ikke noget skema for svarene 400 og 404 ovenfor. Fordi vi definerede en tom @Indhold for dem vises kun deres beskrivelser.

10. Kotlin Support

Da Spring Boot 2.x har førsteklasses support til Kotlin, understøtter SpringDoc dette JVM-sprog ud af boksen til Boot 2.x-applikationer.

For at se dette i aktion opretter vi et simpelt Foo API i Kotlin.

Efter den første opsætning tilføjer vi en dataklasse og en controller. Vi tilføjer dem i en underpakke af vores Boot App, så når den køres, vælger den vores FooController op 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 = "Fundet Foos", indhold = [(Content (mediaType = "applikation / json", array = (ArraySchema (skema = Skema (implementering = Foo :: klasse)))))), ApiResponse (responsCode = "400 ", beskrivelse =" Dårlig anmodning ", indhold = [Content ()]), ApiResponse (responsCode =" 404 ", beskrivelse =" Fandt ingen Foos ", content = [Content ()])]) @GetMapping (" / foo ") sjov getAllFoos (): Liste = fooList}

Nu når vi rammer vores API-dokumentations-URL, ser vi Foo API også:

For at forbedre understøttelsen af ​​Kotlin-typer kan vi tilføje denne afhængighed:

 org.springdoc springdoc-openapi-kotlin

Derefter vil vores Foo-skema se mere informativt ud. På samme måde som det gjorde, da vi havde tilføjet JSR-303 Bean Validation:

11. Konklusion

I denne artikel lærte vi at oprette springdoc-openapi i vores projekter. Derefter så vi, hvordan vi integrerer springdoc-openapi med Swagger UI. Vi så også, hvordan man gør dette med Spring Webflux-projekter.

Dernæst brugte vi springdoc-openapi Maven Plugin til at generere OpenAPI-definitioner til vores API'er, og vi så, hvordan vi eksponerede personsøgnings- og sorteringsoplysninger fra Spring Data. Derefter kiggede vi på, hvordan springdoc-openapi genererer dokumentation automatisk ved hjælp af JSR 303 beanvalideringsnotater og @ResponseStatus kommentarer i @ControllerAdvice klasse.

Derefter lærte vi, hvordan vi tilføjede en beskrivelse til vores API ved hjælp af et par OpenAPI-specifikke kommentarer. Endelig kiggede vi på OpenAPIs støtte til Kotlin.

Springdoc-openapi genererer API-dokumentation ifølge OpenAPI 3-specifikationen. Desuden håndterer den også Swagger UI-konfigurationen for os, hvilket gør API-dokumentgenerering til en ret simpel opgave.

Som altid er koden tilgængelig på GitHub.

Jeg har lige annonceret det nye Lær foråret kursus med fokus på det grundlæggende i Spring 5 og Spring Boot 2: