Dokumentácia Spring REST API pomocou OpenAPI 3.0
Práve som oznámil nové Naučte sa jar kurz zameraný na základy jari 5 a Spring Boot 2:
>> SKONTROLUJTE KURZ1. Prehľad
Dokumentácia je nevyhnutnou súčasťou budovania rozhraní REST API. V tomto tutoriáli sa pozrieme na SpringDoc - nástroj, ktorý zjednodušuje generovanie a údržbu dokumentov API na základe špecifikácie OpenAPI 3 pre aplikácie Spring Boot 1.xa 2.x.
2. Nastavenie springdoc-openapi
Aby Springdoc-openapi automaticky generovalo dokumenty so špecifikáciami OpenAPI 3 pre naše API, jednoducho pridáme springdoc-openapi-ui závislosť na našom pom.xml:
org.springdoc springdoc-openapi-ui 1.5.2 Keď potom spustíme našu aplikáciu, na ceste budú k dispozícii popisy OpenAPI / v3 / api-docs predvolene - napríklad:
// localhost: 8080 / v3 / api-docs /Ak chcete použiť vlastnú cestu, môžeme to označiť v application.properties spis:
springdoc.api-docs.path = / api-docsTeraz budeme mať prístup k dokumentom na adrese:
// localhost: 8080 / api-docs /Definície OpenAPI sú v JSONpredvolene formát. Pre yaml formáte môžeme nájsť definície na:
//localhost:8080/api-docs.yaml3. Nastavenie springdoc-openapi pomocou používateľského rozhrania Swagger
Okrem generovania samotnej špecifikácie OpenAPI 3 môžeme integrovať springdoc-openapi do používateľského rozhrania Swagger, aby sme mohli interagovať s našou špecifikáciou API a vykonávať koncové body.
3.1. Maven závislosť
Všetko, čo musíme urobiť, aby sme nastavili springdoc-openapi s užívateľským rozhraním Swagger, je pridať závislosť springdoc-openapi-ui k projektu pom.xml:
org.springdoc springdoc-openapi-ui 1.5.2 Teraz môžeme získať prístup k dokumentácii API na adrese:
//localhost:8080/swagger-ui.html3.2. Podpora pre swagger-ui Vlastnosti
Springdoc-openapi podporuje aj vlastnosti swagger-ui. Môžu byť použité ako vlastnosti Spring Boot s predponou springdoc.swagger-ui.
Napríklad si prispôsobme cestu k našej dokumentácii API. Môžeme to urobiť úpravou našich application.properties zahrnúť:
springdoc.swagger-ui.path = / swagger-ui-custom.htmlTakže naša dokumentácia k API bude teraz k dispozícii na //localhost:8080/swagger-ui-custom.html.
Ako ďalší príklad môžeme na zoradenie ciest API v poradí podľa ich metód HTTP pridať:
springdoc.swagger-ui.operationsSorter = metóda3.3. Ukážka API
Predpokladajme, že naša aplikácia má radič na správu Knihas:
@RestController @RequestMapping ("/ api / book") verejná trieda BookController {@Autowired súkromné úložisko BookRepository; @GetMapping ("/ {id}") verejná kniha findById (@PathVariable long id) {return repository.findById (id) .orElseThrow (() -> new BookNotFoundException ()); } @GetMapping ("/") public Collection findBooks () {return repository.getBooks (); } @PutMapping ("/ {id}") @ResponseStatus (HttpStatus.OK) verejná kniha updateBook (@PathVariable ("id") final String id, @RequestBody final Book book) {návratová kniha; }} Potom, keď spustíme našu aplikáciu, si môžeme pozrieť dokumentáciu na adrese:
//localhost:8080/swagger-ui-custom.html
Poďme prejsť na / api / kniha koncový bod a pozrite si podrobnosti jeho žiadosti a odpovede:
4. Integrácia springdoc-openapi s Spring WebFlux
Môžeme integrovať springdoc-openapi a Swagger UI do projektu Spring WebFlux pridaním springdoc-openapi-webflux-ui:
org.springdoc springdoc-openapi-webflux-ui 1.5.2 Rovnako ako predtým budú dokumenty prístupné na adrese:
//localhost:8080/swagger-ui.htmlZa účelom prispôsobenia cesty by sme sem opäť mohli pridať znak springdoc.swagger-ui.cesta majetok v našom application.properties.
5. Odkrytie informácií o stránkovaní
Spring Data JPA sa integruje do Spring MVC úplne bezproblémovo. Jedným príkladom takýchto integrácií je Stránkovateľné podpora:
@GetMapping ("/ filter") verejná stránka filterBooks (pageable pageable) {return repository.getBooks (pageable); }Spočiatku by sme mohli očakávať pridanie SpringDoc stránke, veľkosťa triediť parametre dotazu do vygenerovanej dokumentácie. SpringDoc však predvolene nespĺňa toto očakávanie. Aby sme túto funkciu odomkli, mali by sme pridať springdoc-openapi-data-rest závislosť:
org.springdoc springdoc-openapi-data-rest 1.5.2 Teraz do dokumentácie pridá očakávané parametre dotazu:
6. Používanie pluginu Springdoc-openapi Maven
Knižnica springdoc-openapi poskytuje doplnok Maven springdoc-openapi-maven-plugin pre generovanie popisov OpenAPI v json a yaml formáty.
The springdoc-openapi-maven-plugin plugin pracuje s jar-boot-maven zapojiť. Maven vedie openapi plugin počas integračný test fáza.
Pozrime sa, ako môžeme nakonfigurovať doplnok v našom pom.xml:
org.springframework.boot spring-boot-maven-plugin 2.3.3. RELEASE predintegračný test štart po integračnom teste zastaviť org.springdoc springdoc-openapi-maven-plugin 0.2 integračný test generovať Tiež môžeme nakonfigurovať doplnok tak, aby používal vlastné hodnoty:
......... // localhost: 8080 / v3 / api-docs openapi.json $ {project.build.directory} Pozrime sa podrobnejšie na parametre, ktoré môžeme nakonfigurovať pre doplnok:
- apiDocsUrl - URL, kde je možné k dokumentom pristupovať vo formáte JSON, s predvolenou hodnotou // localhost: 8080 / v3 / api-docs
- outputFileName - Názov súboru, v ktorom sú uložené definície, predvolené je openapi.json
- výstupDir - Absolútna cesta k adresáru, v ktorom sú uložené dokumenty - predvolene, $ {project.build.directory}
7. Automatické generovanie dokumentu pomocou validácie Bean JSR-303
Keď náš model obsahuje anotácie overenia fazule JSR-303, ako napr @NotNull, @NotBlank, @ Veľkosť, @ Mina @ Max, knižnica springdoc-openapi ich používa na generovanie dodatočnej dokumentácie schémy pre príslušné obmedzenia.
Pozrime sa na príklad pomocou nášho Kniha fazuľa:
public class Book {private long id; @NotBlank @Size (min = 0, max = 20) názov súkromného reťazca; @NotBlank @Size (min = 0, max = 30) súkromný autor reťazca; }Teraz sa vygeneruje dokumentácia pre Kniha fazuľa je trochu informatívnejšia:
8. Vytvorte dokumentáciu pomocou @ControllerAdvice a @ResponseStatus
Použitím @ResponseStatus o metódach v a @RestControllerAdvice trieda automaticky vygeneruje dokumentáciu pre kódy odpovedí. V tomto @RestControllerAdvice triedy sú tieto dve metódy anotované @ResponseStatus:
@RestControllerAdvice verejná trieda GlobalControllerExceptionHandler {@ExceptionHandler (ConversionFailedException.class) @ResponseStatus (HttpStatus.BAD_REQUEST) public ResponseEntity handleConnversion (RuntimeException ex) {return new ResponseEntity (ex.getMessage (), HttpStatus.BAD_REQUEST) } @ExceptionHandler (BookNotFoundException.class) @ResponseStatus (HttpStatus.NOT_FOUND) public ResponseEntity handleBookNotFound (RuntimeException ex) {return new ResponseEntity (ex.getMessage (), HttpStatus.NOT_FOUND); }}Vo výsledku si teraz môžeme pozrieť dokumentáciu pre kódy odpovedí 400 a 404:
9. Vytvorte dokumentáciu pomocou @ Prevádzka a @ApiResponses
Ďalej sa pozrime, ako môžeme do API pridať nejaký popis pomocou niekoľkých anotácií špecifických pre OpenAPI.
Za týmto účelom urobíme anotáciu nášho kontrolóra / api / book / {id} koncový bod s @ Prevádzka a @ApiResponses:
@Operation (summary = "Získajte knihu podľa jej ID") @ApiResponses (value = {@ApiResponse (responseCode = "200", description = "Nájdená kniha", content = {@Content (mediaType = "application / json") , schema = @Schema (implementation = Book.class))}), @ApiResponse (responseCode = "400", description = "Zadané neplatné ID", content = @Content), @ApiResponse (responseCode = "404", description = „Kniha sa nenašla“, content = @Content)}) @GetMapping ("/ {id}") verejná kniha findById (@Parameter (description = "ID knihy, ktorá sa má prehľadať") @PathVariable dlhé ID) {návratové úložisko. findById (id) .orElseThrow (() -> nový BookNotFoundException ()); }A tu je efekt:
Ako vidíme, text, do ktorého sme pridali @ Prevádzka je umiestnený na operačnej úrovni API. Podobne sa popis pridal k rôznym @ApiResponse prvky v @ApiResponses je tu tiež viditeľná anotácia kontajnera, ktorá dodáva našim odpovediam API význam.
Je zrejmé, že pre odpovede 400 a 404 vyššie nedostaneme nijakú schému. Pretože sme definovali prázdny @ Obsah pre nich sa zobrazia iba ich popisy.
10. Podpora Kotlin
Pretože Spring Boot 2.x má prvotriednu podporu pre Kotlin, SpringDoc podporuje tento jazyk JVM už pre použitie v Boot 2.x.
Aby sme to videli v akcii, vytvoríme jednoduchý Foo API v Kotline.
Po úvodnom nastavení pridáme dátovú triedu a radič. Pridáme ich do čiastkového balíka našej bootovacej aplikácie, aby si pri spustení vybrala našu FooController spolu s predchádzajúcimi BookController:
@Entity dátová trieda Foo (@Id val id: Long = 0, @NotBlank @Size (min = 0, max = 50) názov val: String = "") @RestController @RequestMapping ("/") trieda 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 = Schema (implementation = Foo :: class)))))])), ApiResponse (responseCode = "400 ", description =" Chybná požiadavka ", content = [Content ()]), ApiResponse (responseCode =" 404 ", description =" Nenašiel som žiadne Foos ", content = [Content ()])]) @GetMapping (" / foo ") zábava getAllFoos (): List = fooList}Teraz, keď narazíme na našu adresu URL dokumentácie k API, uvidíme Foo API tiež:
Na zvýšenie podpory typov Kotlin môžeme pridať túto závislosť:
org.springdoc springdoc-openapi-kotlinPotom bude naša schéma Foo vyzerať informatívnejšie. Podobné, ako keď sme pridali overenie fazule JSR-303:
11. Záver
V tomto článku sme sa naučili nastavovať springdoc-openapi v našich projektoch. Potom sme videli, ako integrovať springdoc-openapi do používateľského rozhrania Swagger. Tiež sme videli, ako to urobiť s projektmi Spring Webflux.
Ďalej sme pomocou Springdoc-openapi Maven Plugin vygenerovali definície OpenAPI pre naše API a videli sme, ako vystaviť informácie o stránkovaní a triedení z Spring Data. Potom sme sa pozreli na to, ako springdoc-openapi generuje dokumentáciu automaticky pomocou anotácií overenia fazule JSR 303 a @ResponseStatus anotácie v @ControllerAdvice trieda.
Potom sme sa naučili, ako pridať popis do nášho API pomocou niekoľkých anotácií špecifických pre OpenAPI. Nakoniec sme sa pozreli na to, ako OpenAPI podporuje Kotlina.
Springdoc-openapi generuje dokumentáciu API podľa špecifikácie OpenAPI 3. Okrem toho pre nás tiež spracováva konfiguráciu používateľského rozhrania Swagger, vďaka čomu je generovanie dokumentov API pomerne jednoduchou úlohou.
Ako vždy, kód je k dispozícii na GitHub.
REST spodok
