streamalism.org

Most jelentettem be az újat Tanulj tavaszt tanfolyam, amelynek középpontjában az 5. tavasz és a tavaszi bakancs 2 alapjai állnak:

1. Áttekintés

A dokumentáció elengedhetetlen része a REST API-k kiépítésének. Ebben az oktatóanyagban megnézzük a SpringDoc-ot - egy eszközt, amely leegyszerűsíti az API-dokumentumok előállítását és karbantartását az OpenAPI 3 specifikáció alapján a Spring Boot 1.x és 2.x alkalmazásokhoz.

2. A springdoc-openapi beállítása

Ahhoz, hogy a springdoc-openapi automatikusan létrehozza az API-ra vonatkozó OpenAPI 3 specifikációs dokumentumokat, egyszerűen hozzáadjuk a springdoc-openapi-ui függőség a mi pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

Ezután, amikor futtatjuk az alkalmazásunkat, az elérési útvonalon elérhetők lesznek az OpenAPI leírások / v3 / api-docs alapértelmezés szerint - például:

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

Egyéni elérési út használatához a alkalmazás.tulajdonságok fájl:

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

Most a következő címen férhetünk hozzá a dokumentumokhoz:

// localhost: 8080 / api-docs /

Az OpenAPI definíciók JSON-ban vannakformátum alapértelmezés szerint. Mert yaml formátumban a definíciókat a következő címen szerezhetjük be:

//localhost:8080/api-docs.yaml

3. A springdoc-openapi beállítása Swagger felhasználói felületen

Magának az OpenAPI 3 specifikációnak a létrehozása mellett integrálhatjuk a springdoc-openapit a Swagger felhasználói felületbe, hogy kölcsönhatásba léphessünk API specifikációnkkal és gyakorolhassuk a végpontokat.

3.1. Maven-függőség

A springdoc-openapi Swagger felhasználói felületen történő beállításához csak a függőség hozzáadása szükséges springdoc-openapi-ui a projekté pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

Most már elérhetjük az API dokumentációt:

//localhost:8080/swagger-ui.html

3.2. Támogatás a swagger-ui Tulajdonságok

A Springdoc-openapi támogatja a swagger-ui tulajdonságokat is. Ezek Spring Boot tulajdonságként használhatók, előtaggal springdoc.swagger-ui.

Például testre szabhatjuk az API dokumentációnk útvonalát. Megtehetjük ezt a sajátunk módosításával alkalmazás.tulajdonságok tartalmazza:

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

Tehát most API dokumentációnk elérhető lesz a címen //localhost:8080/swagger-ui-custom.html.

Másik példa: az API elérési útjainak rendezése a HTTP módszerük szerint hozzáadhatjuk:

springdoc.swagger-ui.operationsSorter = módszer

3.3. Minta API

Tegyük fel, hogy alkalmazásunk rendelkezik vezérlővel a kezeléshez Könyvs:

@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 ("/") nyilvános gyűjtemény findBooks () {return repository.getBooks (); } @PutMapping ("/ {id}") @ResponseStatus (HttpStatus.OK) nyilvános könyvfrissítési könyv (@PathVariable ("id") végleges karakterlánc azonosító, @RequestBody végleges könyvkönyv) {visszatérési könyv; }} 

Ezután az alkalmazás futtatásakor megtekinthetjük a dokumentációt:

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

Fúrjuk le a / api / könyv végpont, és tekintse meg a kérés és válasz részleteit:

4. A springdoc-openapi integrálása a Spring WebFlux szolgáltatással

A Springdoc-openapi és a Swagger kezelőfelületet hozzáadással integrálhatjuk egy Spring WebFlux projektbe springdoc-openapi-webflux-ui:

 org.springdoc springdoc-openapi-webflux-ui 1.5.2 

És, mint korábban, a dokumentumok a következő címen lesznek elérhetők:

//localhost:8080/swagger-ui.html

Az útvonal testreszabása érdekében itt is hozzáadhatjuk a springdoc.swagger-ui.path ingatlan a mi alkalmazás.tulajdonságok.

5. A lapszámozási információk feltárása

A Spring Data JPA meglehetősen zökkenőmentesen integrálódik a Spring MVC-be. Az ilyen integrációk egyik példája Lapozható támogatás:

@GetMapping ("/ filter") nyilvános oldal filterBooks (lapozható lapozható) {return repository.getBooks (lapozható); }

Először arra számíthatunk, hogy a SpringDoc hozzáad oldalt, méret, és fajta lekérdezési paramétereket a létrehozott dokumentációhoz. Alapértelmezés szerint azonban a SpringDoc nem teljesíti ezt az elvárást. A funkció feloldásához hozzá kell adnunk a springdoc-openapi-data-rest függőség:

 org.springdoc springdoc-openapi-data-rest 1.5.2 

Most hozzáadja a várható lekérdezési paramétereket a dokumentációhoz:

6. A springdoc-openapi Maven plugin használata

A springdoc-openapi könyvtár Maven plugint biztosít springdoc-openapi-maven-plugin OpenAPI leírások generálásához json és yaml formátumok.

A springdoc-openapi-maven-plugin plugin működik a rugós-bakancsos-maven csatlakoztat. Maven fut a openapi bővítmény a integrációs teszt fázis.

Nézzük meg, hogyan konfigurálhatjuk a bővítményt a mi pom.xml:

 org.springframework.boot spring-boot-maven-plugin 2.3.3. KÖZLEMÉNY integráció előtti teszt indítás integráció utáni teszt megállás org.springdoc springdoc-openapi-maven-plugin 0.2 integráció-teszt generálás 

Beállíthatjuk a beépülő modult az egyéni értékek használatára is:

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

Vizsgáljuk meg közelebbről azokat a paramétereket, amelyeket konfigurálhatunk a beépülő modulhoz:

• apiDocsUrl - URL, ahol a dokumentumok JSON formátumban érhetők el, alapértelmezettként // localhost: 8080 / v3 / api-docs
• kimeneti fájl név - A fájl neve, ahol a definíciókat tárolják, alapértelmezés szerint openapi.json
• outputDir - Abszolút elérési út annak a könyvtárnak, ahol a dokumentumok vannak tárolva - alapértelmezés szerint, $ {project.build.directory}

7. Automatikus dokumentumgenerálás a JSR-303 babellenőrzéssel

Amikor a modellünk JSR-303 babellenőrzési jegyzeteket tartalmaz, mint pl @Nem nulla, @NotBlank, @Méret, @Min, és @Max, a springdoc-openapi könyvtár felhasználja őket további séma-dokumentumok létrehozására a megfelelő korlátozásokhoz.

Lássunk egy példát a mi használatunkkal Könyv bab:

public class Book {private long id; @NotBlank @Size (min = 0, max = 20) privát karakterlánc címe; @NotBlank @Size (min = 0, max = 30) privát karakterlánc szerző; }

Most a Könyv bab egy kicsit informatívabb:

8. Dokumentáció előállítása a @ControllerAdvice és @ResponseStatus

Használata @ResponseStatus a módszerekről a @RestControllerAdvice osztály automatikusan elkészíti a válaszkódok dokumentációját. Ebben @RestControllerAdvice osztályban a két módszert feljegyzik @ResponseStatus:

@RestControllerAdvice nyilvános osztály GlobalControllerExceptionHandler {@ExceptionHandler (ConversionFailedException.class) @ResponseStatus (HttpStatus.BAD_REQUEST) public ResponseEntity handleConnversion (RuntimeException ex) {return new ResponseEttage (ReturnStesture.ttp; } @ExceptionHandler (BookNotFoundException.class) @ResponseStatus (HttpStatus.NOT_FOUND) public ResponseEntity handleBookNotFound (RuntimeException ex) {return new ResponseEntity (ex.getMessage (), HttpStatus.NOT_FOUND; }}

Ennek eredményeként láthatjuk a 400 és 404 válaszkódok dokumentációját:

9. Dokumentáció előállítása a @Művelet és @ApiResponses

Ezután nézzük meg, hogyan adhatunk hozzá néhány leírást az API-hoz néhány OpenAPI-specifikus kommentár segítségével.

Ennek érdekében jegyzetekkel ellátjuk kontrollerünket / api / book / {id} végpont a @Művelet és @ApiResponses:

@Operation (összefoglaló = "Könyv beszerzése az azonosító alapján") @ApiResponses (érték = {@ApiResponse (responseCode = "200", description = "Megtaláltam a könyvet", content = {@Content (mediaType = "application / json") , schema = @Schema (implementáció = Book.class))}), @ApiResponse (responseCode = "400", description = "Érvénytelen azonosító van megadva, content = @Content), @ApiResponse (responseCode =" 404 ", description = "A könyv nem található", content = @Content)}) @GetMapping ("/ {id}") public Book findById (@Parameter (description = "a keresendő könyv azonosítója") @PathVariable long id) {visszatérési adattár. findById (id) .orElseThrow (() -> new BookNotFoundException ()); }

És itt van a hatás:

Mint láthatjuk, a szöveg, amelyhez hozzáadtuk @Művelet az API működési szintjén van elhelyezve. Hasonlóképpen, a leírás kiegészült különféle @ApiResponse elemei a @ApiResponses a konténer kommentár itt is látható, jelentést adva az API-válaszainknak.

Nyilvánvalóan nem kapunk sémát a fenti 400 és 404 válaszokhoz. Mert definiáltunk egy üreset @Tartalom számukra csak a leírásuk jelenik meg.

10. Kotlin támogatás

Mivel a Spring Boot 2.x első osztályú támogatást nyújt a Kotlin számára, a SpringDoc támogatja a JVM nyelvet a dobozból a Boot 2.x alkalmazásokhoz.

Ahhoz, hogy ezt működés közben lássuk, létrehozunk egy egyszerűt Foo API Kotlinban.

A kezdeti beállítás után hozzáadunk egy adatosztályt és egy vezérlőt. Felvesszük őket a Boot alkalmazásunk egyik alcsomagjába, hogy futtatásakor válasszon minket FooController fel a korábbival együtt BookController:

@Entity adatosztály 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 (összefoglaló = "Get all foos") @ApiResponses (value = [ApiResponse (responseCode = "200"), description = "Talált Foos", content = [(Content (mediaType = "application / json", array = (ArraySchema (schema = Schema (implementáció = Foo :: class)))))]]]), ApiResponse (responseCode = "400 ", description =" Rossz kérés ", content = [Content ()]), ApiResponse (responseCode =" 404 ", description =" Nem találtam Foos ", content = [Content ()])]] @GetMapping (" / foo ") fun getAllFoos (): List = fooList}

Most, amikor elérjük az API dokumentáció URL-jünket, látni fogjuk a Foo API is:

A Kotlin típusok támogatásának fokozása érdekében felvehetjük ezt a függőséget:

 org.springdoc springdoc-openapi-kotlin

Ezt követően a Foo sémánk informatívabbnak tűnik. Hasonló, mint akkor, amikor hozzáadtuk a JSR-303 babellenőrzést:

11. Következtetés

Ebben a cikkben megtanultuk a springdoc-openapi beállítását projektjeinkben. Aztán láttuk, hogyan lehet integrálni a springdoc-openapi programot a Swagger felhasználói felületbe. Azt is láttuk, hogyan lehet ezt megtenni a Spring Webflux projektekkel.

Ezután a springdoc-openapi Maven beépülő modult használtuk az API-k OpenAPI-definícióinak előállításához, és láttuk, hogyan lehet kitenni a lapozási és rendezési információkat a Spring Data-ból. Ezt követően megvizsgáltuk, hogy a springdoc-openapi hogyan generálja a dokumentációt automatikusan a JSR 303 bab validációs kommentárok és a @ResponseStatus annotációk @ControllerAdvice osztály.

Ezután megtanultuk, hogyan lehet leírást hozzáadni az API-hoz néhány OpenAPI-specifikus kommentár segítségével. Végül egy pillantást vetettünk az OpenAPI Kotlin támogatására.

A springdoc-openapi az API dokumentációt állítja elő az OpenAPI 3 specifikáció szerint. Ezenkívül kezeli számunkra a Swagger felhasználói felület konfigurációját is, így az API-dokumentumok létrehozása meglehetősen egyszerű feladat.

Mint mindig, a kód elérhető a GitHubon.

Most jelentettem be az újat Tanulj tavaszt tanfolyam, amelynek középpontjában az 5. tavasz és a tavaszi bakancs 2 alapjai állnak: