streamalism.org

Upravo sam najavio novo Uči proljeće tečaj, usredotočen na osnove Spring 5 i Spring Boot 2:

1. Pregled

Dokumentacija je bitan dio izgradnje REST API-ja. U ovom uputstvu ćemo pogledati SpringDoc - alat koji pojednostavljuje generiranje i održavanje API dokumenata, na temelju OpenAPI 3 specifikacije, za Spring Boot 1.x i 2.x aplikacije.

2. Postavljanje springdoc-openapija

Da bi springdoc-openapi automatski generirao dokumente OpenAPI 3 specifikacije za naš API, jednostavno dodajemo springdoc-openapi-ui ovisnost o našoj pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

Tada, kad pokrenemo našu aplikaciju, opisi OpenAPI-a bit će dostupni na putu / v3 / api-docs prema zadanim postavkama - na primjer:

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

Da bismo koristili prilagođenu stazu, možemo označiti u primjena.svojstva datoteka:

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

Sada ćemo moći pristupiti dokumentima na:

// localhost: 8080 / api-docs /

Definicije OpenAPI su u JSON-uformat prema zadanim postavkama. Za yaml formatu, definicije možemo dobiti na:

//localhost:8080/api-docs.yaml

3. Postavljanje springdoc-openapija s Swagger korisničkim sučeljem

Osim generiranja same OpenAPI 3 specifikacije, možemo integrirati springdoc-openapi sa Swagger korisničkim sučeljem kako bismo mogli komunicirati s našom API specifikacijom i vježbati krajnje točke.

3.1. Ovisnost Mavena

Sve što moramo učiniti da bismo postavili springdoc-openapi sa Swagger UI je dodati ovisnost springdoc-openapi-ui projektima pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

API dokumentaciji sada možemo pristupiti na:

//localhost:8080/swagger-ui.html

3.2. Podrška za šepurenje-ui Svojstva

Springdoc-openapi također podržava svojstva swagger-ui. Oni se mogu koristiti kao svojstva Spring Boot, s prefiksom springdoc.swagger-ui.

Na primjer, prilagodimo put naše API dokumentacije. To možemo učiniti mijenjanjem našeg primjena.svojstva uključiti:

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

Dakle, sada će naša API dokumentacija biti dostupna na //localhost:8080/swagger-ui-custom.html.

Kao drugi primjer, za razvrstavanje API staza po redoslijedu njihovih HTTP metoda možemo dodati:

springdoc.swagger-ui.operationsSorter = metoda

3.3. Primjer API-ja

Pretpostavimo da naša aplikacija ima kontroler za upravljanje Knjigas:

@RestController @RequestMapping ("/ api / book") javna klasa BookController {@Autowired privatno spremište BookRepository; @GetMapping ("/ {id}") javna knjiga findById (@PathVariable long id) {return repository.findById (id) .orElseThrow (() -> new BookNotFoundException ()); } @GetMapping ("/") javna zbirka findBooks () {return repository.getBooks (); } @PutMapping ("/ {id}") @ResponseStatus (HttpStatus.OK) javna knjiga ažuriranja knjige (@PathVariable ("id") final String id, @RequestBody final Book book) {return book; }} 

Zatim, kada pokrenemo našu aplikaciju, dokumentaciju možemo pregledati na:

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

Razmotrimo na / api / knjiga krajnju točku i pogledajte detalje za njezin zahtjev i odgovor:

4. Integriranje springdoc-openapija s Spring WebFluxom

Dodavanjem možemo integrirati springdoc-openapi i Swagger UI u projekt Spring WebFlux springdoc-openapi-webflux-ui:

 org.springdoc springdoc-openapi-webflux-ui 1.5.2 

I, kao i prije, dokumentima će se moći pristupiti na:

//localhost:8080/swagger-ui.html

Da bismo prilagodili put, ovdje bismo opet mogli dodati springdoc.swagger-ui.path vlasništvo u našem primjena.svojstva.

5. Izlaganje informacija o paginaciji

Spring Data JPA integrira se s Spring MVC prilično neprimjetno. Jedan od primjera takvih integracija je Pageable podrška:

@GetMapping ("/ filter") javna stranica filterBooks (stranica koja se može stranicati) {return repository.getBooks (stranica koja se može stranicati); }

U početku bismo mogli očekivati ​​dodavanje SpringDoca stranica, veličina, i vrsta parametri upita za generiranu dokumentaciju. Međutim, prema zadanim postavkama SpringDoc ne ispunjava ovo očekivanje. Da bismo otključali ovu značajku, trebali bismo dodati springdoc-openapi-data-rest ovisnost:

 org.springdoc springdoc-openapi-data-rest 1.5.2 

Sada dodaje očekivane parametre upita u dokumentaciju:

6. Korištenje dodatka Springdoc-openapi Maven

Knjižnica springdoc-openapi nudi dodatak Maven dodatak springdoc-openapi-maven-plugin za generiranje OpenAPI opisa u json i yaml formati.

The dodatak springdoc-openapi-maven-plugin dodatak radi s proljeće-čizma-maven uključiti. Maven upravlja openapi dodatak tijekom integracija-test faza.

Pogledajmo kako možemo konfigurirati dodatak u našem pom.xml:

 org.springframework.boot spring-boot-maven-plugin 2.3.3.OBUŠTENJE predintegriranje-test start post-integracija-test stop org.springdoc springdoc-openapi-maven-plugin 0.2 integracija-test generiranje 

Također, dodatak možemo konfigurirati da koristi prilagođene vrijednosti:

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

Pogledajmo bliže parametre koje možemo konfigurirati za dodatak:

• apiDocsUrl - URL na kojem se dokumentima može pristupiti u JSON formatu, sa zadanim // localhost: 8080 / v3 / api-docs
• outputFileName - Naziv datoteke u kojoj su pohranjene definicije, prema zadanim postavkama openapi.json
• outputDir - Apsolutni put do direktorija u kojem su pohranjeni dokumenti - prema zadanim postavkama $ {project.build.directory}

7. Automatsko generiranje dokumenata pomoću provjere zrna JSR-303

Kada naš model uključuje napomene za provjeru graha JSR-303, kao što su @NotNull, @NetBlank, @Veličina, @ Min, i @Max, knjižnica springdoc-openapi koristi ih za generiranje dodatne dokumentacije sheme za odgovarajuća ograničenja.

Pogledajmo primjer koristeći naš Knjiga grah:

javna klasa Book {private long id; @NotBlank @Size (min = 0, max = 20) naslov privatnog niza; @NotBlank @Size (min = 0, max = 30) autor privatnog niza; }

Sada je dokumentacija generirana za Knjiga grah je malo informativniji:

8. Izrada dokumentacije pomoću @ControllerAdvice i @ResponseStatus

Koristeći @ResponseStatus o metodama u a @RestControllerAdvice klasa će automatski generirati dokumentaciju za kodove odgovora. U ovome @RestControllerAdvice klase, dvije metode su označene sa @ResponseStatus:

@RestControllerAdvice javna klasa GlobalControllerExceptionHandler {@ExceptionHandler (ConversionFailedException.class) @ResponseStatus (HttpStatus.BAD_REQUEST) public ResponseEntity handleConnversion (RuntimeException ex) {return newStaption } @ExceptionHandler (BookNotFoundException.class) @ResponseStatus (HttpStatus.NOT_FOUND) javni ResponseEntity handleBookNotFound (RuntimeException ex) {return new ResponseEntity (ex.getMessage (), HttpStatOU.N; }}

Kao rezultat, sada možemo vidjeti dokumentaciju za kodove odgovora 400 i 404:

9. Generirajte dokumentaciju pomoću @ Operacija i @ApiResponses

Dalje, pogledajmo kako možemo dodati neki opis našem API-ju pomoću nekoliko napomena specifičnih za OpenAPI.

Da bismo to učinili, označit ćemo naš kontroler / api / book / {id} krajnja točka sa @ Operacija i @ApiResponses:

@Operation (summary = "Nabavite knjigu prema njenom ID-u") @ApiResponses (value = {@ApiResponse (responseCode = "200", description = "Found the book", content = {@Content (mediaType = "application / json") , schema = @Schema (implementacija = Book.class))}), @ApiResponse (responseCode = "400", description = "Dostavljen nevažeći ID", content = @Content), @ApiResponse (responseCode = "404", description = "Knjiga nije pronađena", content = @Content)}) @GetMapping ("/ {id}") public Book findById (@Parameter (description = "id knjige koju treba pretražiti") @PathVariable long id) {repozitorij. findById (id) .orElseThrow (() -> novi BookNotFoundException ()); }

A evo i učinka:

Kao što vidimo, tekst koji smo dodali @ Operacija postavljen je na razinu rada API-ja. Slično tome, opis dodan raznim @ApiResponse elementi u @ApiResponses Ovdje je vidljiva i bilješka o spremniku, dodajući značenje našim API odgovorima.

Očito ne dobivamo nikakvu shemu za odgovore 400 i 404 gore. Jer smo definirali prazno @Sadržaj za njih su prikazani samo njihovi opisi.

10. Kotlin podrška

Budući da Spring Boot 2.x ima prvoklasnu podršku za Kotlin, SpringDoc podržava ovaj JVM jezik iz kutije za aplikacije Boot 2.x.

Da bismo to vidjeli na djelu, stvorit ćemo jednostavan Foo API u Kotlinu.

Nakon početnog postavljanja, dodat ćemo podatkovnu klasu i kontroler. Dodati ćemo ih u podpaket naše aplikacije za pokretanje tako da, kada se pokrene, odabere našu FooController gore zajedno s ranijim BookController:

Klasa podataka @Entity 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", description = "Found Foos", content = [(Content (mediaType = "application / json", array = (ArraySchema (schema = Shema (implementacija = Foo :: class))))))))), ApiResponse (responseCode = "400 ", description =" Loš zahtjev ", content = [Content ()]), ApiResponse (responseCode =" 404 ", description =" Nije pronađen nijedan Foos ", content = [Content ()])]) @GetMapping (" / foo ") zabava getAllFoos (): List = fooList}

Sad kad dođemo do URL-a naše API dokumentacije, vidjet ćemo Foo API također:

Da bismo poboljšali podršku za vrste Kotlin, možemo dodati ovu ovisnost:

 org.springdoc springdoc-openapi-kotlin

Nakon toga, naša Foo shema izgledat će informativnije. Slično kao što je bilo kad smo dodali JSR-303 provjeru graha:

11. Zaključak

U ovom smo članku naučili postavljati springdoc-openapi u našim projektima. Zatim smo vidjeli kako integrirati springdoc-openapi s Swagger korisničkim sučeljem. Također smo vidjeli kako to učiniti s projektima Spring Webflux.

Dalje, koristili smo dodatak springdoc-openapi Maven za generiranje OpenAPI definicija za naše API-je i vidjeli smo kako izložiti informacije o straničenju i sortiranju iz Spring Data. Nakon toga smo pogledali kako springdoc-openapi automatski generira dokumentaciju koristeći bilješke provjere valjanosti JSR 303 i @ResponseStatus bilješke u @ControllerAdvice razred.

Tada smo naučili kako dodati opis u naš API koristeći nekoliko napomena specifičnih za OpenAPI. Napokon smo zavirili u podršku OpenAPI-a za Kotlina.

Springdoc-openapi generira API dokumentaciju prema OpenAPI 3 specifikaciji. Štoviše, on također obrađuje konfiguraciju korisničkog sučelja Swagger za nas, što generiranje API dokumenta čini prilično jednostavnim zadatkom.

Kao i uvijek, kôd je dostupan na GitHub-u.

Upravo sam najavio novo Uči proljeće tečaj, usredotočen na osnove Spring 5 i Spring Boot 2: