A Swagger 2 beállítása Spring REST API-val
Most jelentettem be az új Learn Spring Security tanfolyamot, beleértve a Spring Security 5 új OAuth2 veremére összpontosító teljes anyagot:
>> ELLENŐRIZZE A FOLYAMATOT REST felsőMost jelentettem be az újat Tanulj tavaszt tanfolyam, amelynek középpontjában az 5. tavasz és a tavaszi bakancs 2 alapjai állnak:
>> ELLENŐRIZZE A FOLYAMATOT1. Áttekintés
Manapság a front-end és a back-end komponensek gyakran különítenek el egy webalkalmazást. Általában az API-kat háttér-összetevőként tesszük közzé a front-end komponens vagy a harmadik féltől származó alkalmazásintegrációk számára.
Ilyen esetekben elengedhetetlen a háttér-API-k megfelelő specifikációinak megléte. Ugyanakkor az API dokumentációjának informatívnak, olvashatónak és könnyen követhetőnek kell lennie.
Ezenkívül a referencia-dokumentációnak egyszerre kell leírnia az API minden változását. Ennek manuális végrehajtása unalmas feladat, ezért elkerülhetetlen volt a folyamat automatizálása.
Ebben az oktatóanyagban megnézzük Swagger 2 a Spring REST webszolgáltatásért, a Swagger 2 specifikáció Springfox implementációját használva.
Ha még nem ismeri a Swaggert, látogasson el a weboldalára, és tudjon meg többet, mielőtt folytatja az oktatóanyagot.
2. Cél projekt
Az általunk használt REST szolgáltatás létrehozása nem tartozik a cikk hatálya alá. Ha már rendelkezik megfelelő projekttel, használja azt. Ha nem, akkor ezek a linkek jó kiindulópontok:
- Hozzon létre egy REST API-t a Spring 4 és a Java Config cikkel
- RESTful webszolgáltatás kiépítése
3. A Maven-függőség hozzáadása
Mint fent említettük, a Swagger specifikáció Springfox implementációját fogjuk használni. A legújabb verzió megtalálható a Maven Central oldalon.
A Maven projektünkhöz való hozzáadásához szükségünk van egy függőségre a pom.xml fájl:
io.springfox springfox-swagger2 2.9.2 3.1. Tavaszi bakancsfüggőség
A Spring Boot alapú projekteknél elég egy kislemez hozzáadása springfox-boot-starter függőség:
io.springfox springfox-boot-starter 3.0.0 4. A Swagger 2 integrálása a projektbe
4.1. Java konfiguráció
A Swagger konfigurációja főleg a Jegyzék bab:
@Configuration public class SpringFoxConfig {@Bean public Docket api () {return new Docket (DocumentationType.SWAGGER_2) .select () .apis (RequestHandlerSelectors.any ()) .paths (PathSelectors.any ()) .build (); }}Miután meghatározta a Jegyzék bab, annak válassza () metódus adja vissza a ApiSelectorBuilder, amely lehetőséget nyújt a Swagger által kitett végpontok ellenőrzésére.
Beállíthatunk predikátumokat a kiválasztáshoz RequestHandlers segítségével RequestHandlerSelectors és PathSelectors. Használata Bármi() mert mindkettő a Swaggeren keresztül elérhetővé teszi az egész API-ra vonatkozó dokumentációt.
4.2. Konfiguráció rugós indítás nélkül
A sima tavaszi projektekben kifejezetten engedélyeznünk kell a Swagger 2 programot. Ehhez használnunk kell a @ EnableSwagger2WebMvc konfigurációs osztályunkon:
@Configuration @ EnableSwagger2WebMvc public class SpringFoxConfig {}Ráadásul a Spring Boot nélkül nincs lehetőségünk az erőforrás-kezelőink automatikus konfigurálására.
A Swagger felhasználói felület egy erőforráskészletet ad hozzá, amelyet egy kiterjesztett osztály részeként kell konfigurálnunk WebMvcConfigurerAdapter és azzal van jelölve @EnableWebMvc:
@Orride public void addResourceHandlers (ResourceHandlerRegistry registry) {register.addResourceHandler ("swagger-ui.html") .addResourceLocations ("classpath: / META-INF / resources /"); register.addResourceHandler ("/ webjars / **") .addResourceLocations ("classpath: / META-INF / resources / webjars /"); }4.3. Igazolás
Annak ellenőrzésére, hogy a Springfox működik-e, felkereshetjük ezt az URL-t a böngészőnkben:
// localhost: 8080 / spring-security-rest / api / v2 / api-docs
Az eredmény egy JSON válasz, nagyszámú kulcs-érték párral, ami nem túl emberileg olvasható. Szerencsére Swagger biztosítja Swagger felhasználói felület erre a célra.
5. Swagger felhasználói felület
A Swagger UI egy beépített megoldás, amely sokkal könnyebbé teszi a felhasználói interakciókat a Swagger által generált API dokumentációval.
5.1. A Springfox Swagger felhasználói felületének engedélyezése
A Swagger felhasználói felület használatához hozzá kell adnunk egy további Maven-függőséget:
io.springfox springfox-swagger-ui 2.9.2 Most kipróbálhatjuk a böngészőnkben a következő címen:
// localhost: 8080 / your-app-root / swagger-ui /
Esetünkben egyébként a pontos URL a következő lesz:
// localhost: 8080 / spring-security-rest / api / swagger-ui /
Az eredménynek így kell kinéznie:
5.2. Swagger Dokumentáció feltárása
Swagger válaszán belül a az összes vezérlő listája az alkalmazásunkban meghatározott. Bármelyikre kattintva felsoroljuk az érvényes HTTP módszereket (TÖRÖL, KAP, FEJ, OPCIÓK, TAPASZ, POST, PUT).
Az egyes módszerek kibővítése további hasznos adatokat tartalmaz, például a válasz állapotát, a tartalom típusát és a paraméterek listáját. Lehetséges az egyes módszerek kipróbálása a felhasználói felület használatával is.
A Swagger képessége, hogy szinkronizálódjon a kódalapunkkal, döntő fontosságú. Ennek bemutatásához új vezérlőt adhatunk alkalmazásunkhoz:
@RestController public class CustomController {@RequestMapping (value = "/ custom", method = RequestMethod.POST) public String custom () {return "custom"; }}Ha frissítjük a Swagger dokumentációt, akkor látjuk custom-controller a vezérlők listáján. Mint tudjuk, csak egy módszer létezik (POST) látható Swagger válaszában.
6. Tavaszi adatok REST
A Springfox ezen keresztül nyújt támogatást a Spring Data REST számára springfox-data-rest könyvtár.
A Spring Boot gondoskodik az automatikus konfigurációról, ha felfedezi a tavasz-boot-starter-data-rest az osztályúton.
Most hozzunk létre egy nevű entitást Felhasználó:
@Entity public class User {@Id private Long id; privát karakterlánc keresztnév; privát int kor; privát karakterlánc e-mail; // szerelők és beállítók}Akkor létrehozzuk a UserRepository CRUD műveletek hozzáadásához a Felhasználó entitás:
@Repository nyilvános felület A UserRepository kiterjeszti a CrudRepository {}Utoljára importáljuk a SpringDataRestConfiguration osztály a SpringFoxConfig osztály:
@ EnableSwagger2WebMvc @Import (SpringDataRestConfiguration.class) public class SpringFoxConfig {// ...}Megjegyzés: A @ EnableSwagger2WebMvc megjegyzés a Swagger engedélyezéséhez, mivel az felváltotta a @ EnableSwagger2 annotáció a könyvtárak 3. verziójában.
Indítsuk újra az alkalmazást a Spring Data REST API-k specifikációinak előállításához:
Láthatjuk, hogy a Springfox elkészítette a Felhasználó entitás HTTP módszerekkel, például KAP, POST, PUT, PATCH, és TÖRÖL.
7. Babellenőrzés
A Springfox a bab-hitelesítési jelöléseket is támogatja springfox-bab-validátorok könyvtár.
Először hozzáadjuk a Maven-függőséget pom.xml:
io.springfox springfox-bab-validátorok 2.9.2 Újra, ha a Spring Boot-ot használjuk, akkor nem kell kifejezetten megadnunk a fenti függőséget.
Ezután adjunk hozzá néhány érvényesítési megjegyzést, például @Nem nulla és @Min hoz Felhasználó entitás:
@Entity public class Felhasználó {// ... @NotNull (message = "A keresztnév nem lehet null") private String keresztnév; @Min (érték = 15, üzenet = "Az életkor nem lehet kevesebb 15-nél") @Max (érték = 65, üzenet = "Az életkor nem lehet nagyobb 65-nél") private int age; }Végül importáljuk a BeanValidatorPluginsConfiguration osztály a SpringFoxConfig osztály:
@ EnableSwagger2 @Import (BeanValidatorPluginsConfiguration.class) public class SpringFoxConfig {// ...}Vessünk egy pillantást az API specifikációk változásaira:
Itt megfigyelhetjük, hogy a Felhasználó modell rendelkezik * szükséges a keresztnév. Továbbá a minimális és maximális értékei vannak meghatározva a kor.
8. Bővítmény
Annak érdekében, hogy specifikus szolgáltatásokat adjunk az API specifikációkhoz, létrehozhatunk egy Springfox beépülő modult. A plugin különféle szolgáltatásokat kínál, a modellek és tulajdonságok gazdagításától kezdve az egyéni API-listákig és alapértelmezésekig.
A Springfox a spi modulján keresztül támogatja a plugin létrehozását. A spi modul néhány interfészt biztosít, például a ModelBuilderPlugin, ModelPropertyBuilderPlugin, és ApiListingBuilderPlugin amelyek kibővíthetőségi kampóként működnek egy egyedi plugin megvalósításához.
A képességek bemutatásához hozzunk létre egy bővítményt a gazdagításhoz email tulajdona Felhasználó modell. Használjuk a ModelPropertyBuilderPlugin interfész és állítsa be a minta és példa.
Először hozzuk létre a EmailAnnotationPlugin osztály és felülírja a támogatja módszer bármilyen dokumentációs típus, például a Swagger 1.2 és a Swagger 2 engedélyezésére:
@Component @Order (Validators.BEAN_VALIDATOR_PLUGIN_ORDER) public class EmailAnnotationPlugin implementálja a ModelPropertyBuilderPlugin {@Orride public boolean support (DocumentationType delimiter) {return true; }}Akkor felülírjuk a alkalmaz módszere ModelPropertyBuilderPlugin az építő tulajdonságainak értékeinek beállításához:
@ Nyilvános érvénytelenítés érvénytelenítése (ModelPropertyContext context) {Opcionális email = annotationFromBean (context, Email.class); if (email.isPresent ()) {context.getSpecificationBuilder (). facetBuilder (StringElementFacetBuilder.class) .pattern (email.get (). regexp ()); context.getSpecificationBuilder (). example ("[email protected]"); }}Tehát az API specifikációk megmutatják a minta és példa tulajdonsággal annotált értékei @Email annotáció.
Ezután hozzáadjuk a @Email jegyzet a Felhasználó entitás:
@Entity public class Felhasználó {// ... @Email (regexp = ". * @. * \ .. *", message = "Az e-mailnek érvényesnek kell lennie") privát karakterlánc e-mail; }Utoljára engedélyezzük a EmailAnnotationPlugin ban,-ben SpringFoxConfig osztályba babként történő regisztrációval:
@Import ({BeanValidatorPluginsConfiguration.class}) public class SpringFoxConfig {// ... @Bean public EmailAnnotationPlugin emailPlugin () {return new EmailAnnotationPlugin (); }}Nézzük meg a EmailAnnotationPlugin működés közben:
Láthatjuk a minta ugyanaz a regex (. * @. * \ .. *) a email tulajdona Felhasználó entitás.
Hasonlóképpen a példa ([email protected]) megegyezik a alkalmaz módszere EmailAnnotationPlugin.
9. Speciális konfiguráció
A Jegyzék Az alkalmazásunk babja úgy konfigurálható, hogy jobban ellenőrizhessük az API dokumentáció létrehozásának folyamatát.
9.1. Szűrő API Swagger válaszához
Nem mindig kívánatos a teljes API dokumentációjának bemutatása. Korlátozhatjuk Swagger válaszát, ha paramétereket adunk át a apis () és utak () módszerei Jegyzék osztály.
Ahogy fentebb láttuk, RequestHandlerSelectors lehetővé teszi a Bármi vagy egyik sem predikátumok, de felhasználható az API kiszűrésére is az alapcsomag, osztály annotáció és módszer annotációk szerint.
PathSelectors további szűrést biztosít predikátumokkal, amelyek beolvassák alkalmazásunk kérési útjait. Tudjuk használni Bármi(), egyik sem(), regex (), vagy hangya().
Az alábbi példában arra fogjuk utasítani a Swaggert, hogy csak egy vezérlőt vegyen fel egy adott csomagból, meghatározott útvonalakkal, a hangya() állítmány:
@Bean public Docket api () {return new Docket (DocumentationType.SWAGGER_2) .select () .apis (RequestHandlerSelectors.basePackage ("com.baeldung.web.controller")) .paths (PathSelectors.ant ("/ foos / *) ")) .épít(); }9.2. Egyéni információk
A Swagger válaszában néhány alapértelmezett értéket is megad, amelyeket testreszabhatunk, például az „Api Documentation”, a „Created by Contact Email” és az „Apache 2.0”.
Ezen értékek megváltoztatásához használhatjuk a apiInfo (ApiInfo apiInfo) módszer - az ApiInfo osztály, amely egyéni információkat tartalmaz az API-ról:
@Bean public Docket api () {return new Docket (DocumentationType.SWAGGER_2) .select () .apis (RequestHandlerSelectors.basePackage ("com.example.controller")) .paths (PathSelectors.ant ("/ foos / *") ) .build () .apiInfo (apiInfo ()); } private ApiInfo apiInfo () {return new ApiInfo ("My REST API", "Az API néhány egyedi leírása.", "API TOS", "Szolgáltatási feltételek", új névjegy ("John Doe", "www.example. com "," [email protected] ")," API licenc "," API licenc URL ", Collections.emptyList ()); }9.3. Egyéni módszerek Válaszüzenetek
Swagger megengedi a HTTP-módszerek globálisan felülíró válaszüzenetei keresztül Jegyzék’S globalResponseMessage ()módszer.
Először arra kell utasítanunk Swaggert, hogy ne használja az alapértelmezett válaszüzeneteket. Tegyük fel, hogy felül akarjuk írni 500 és 403 válaszüzenetek mindenkinek KAP mód.
Ennek eléréséhez néhány kódot hozzá kell adni a JegyzékInicializáló blokkja (az érthetőség kedvéért az eredeti kód kizárt):
.useDefaultResponseMessages (false) .globalResponseMessage (RequestMethod.GET, newArrayList (new ResponseMessageBuilder () .code (500) .message ("500 message") .responseModel (new ModelRef ("Error")) .build (), new ResponseM ) .code (403) .message ("Tilos!") .build ()));
10. Swagger felhasználói felület OAuth-Secured API-val
A Swagger felhasználói felület számos nagyon hasznos funkciót kínál, amelyekre itt eddig is kitértünk. De ezek nagy részét nem igazán használhatjuk, ha az API-nk biztonságos és nem érhető el.
Nézzük meg, hogyan engedhetjük meg a Swagger számára, hogy hozzáférjen egy OAuth által biztosított API-hoz az ebben a példában szereplő engedélyezési kód használatával.
A Swagger-t úgy konfiguráljuk, hogy hozzáférjen a biztonságos API-hoz a SecurityScheme és SecurityContext támogatás:
@Bean public Docket api () {return new Docket (DocumentationType.SWAGGER_2) .select () .apis (RequestHandlerSelectors.any ()) .paths (PathSelectors.any ()) .build () .securitySchemes (Arrays.asList (securityScheme) ())) .securityContexts (Arrays.asList (securityContext ())); }10.1. A biztonsági konfiguráció
Meghatározzuk a SecurityConfiguration babot a Swagger konfigurációnkban, és állítson be néhány alapértelmezést:
@Bean public SecurityConfiguration security () {return SecurityConfigurationBuilder.builder () .clientId (CLIENT_ID) .clientSecret (CLIENT_SECRET) .scopeSeparator ("") .useBasicAuthenticationWithAccessCodeGrant (true) .build (); }10.2. SecurityScheme
Ezután meghatározzuk a sajátunkat SecurityScheme; ezt arra használjuk, hogy leírjuk az API-junk biztonságát (Basic Authentication, OAuth2,…).
Esetünkben itt meghatározunk egy OAuth-sémát, amelyet az erőforrás-kiszolgálónk védelmére használunk:
privát SecurityScheme securityScheme () {GrantType grantType = new AuthorizationCodeGrantBuilder () .tokenEndpoint (új TokenEndpoint (AUTH_SERVER + "/ token", "oauthtoken")) .tokenRequestEndpoint (új TokenRequestEndpoint (AUTI_SERVER, CLASS_SERVER + "AUTH_SERVER +" épít(); SecurityScheme oauth = new OAuthBuilder (). Name ("spring_oauth") .grantTypes (Arrays.asList (grantType)) .scopes (Arrays.asList (scopes ())) .build (); visszatér oauth; }Ne feledje, hogy az Engedélyezési kód engedélytípust használtuk, amelyhez meg kell adnunk egy token végpontot és az OAuth2 engedélyezési kiszolgálónk engedélyezési URL-jét.
És itt vannak azok a hatókörök, amelyeket meg kell határoznunk:
privát AuthorizationScope [] hatókörök () {AuthorizationScope [] scopes = {új AuthorizationScope ("olvasás", "olvasási műveletekhez"), új AuthorizationScope ("írás", "írási műveletekhez"), új AuthorizationScope ("foo", " Hozzáférés a foo API-hoz ")}; visszatérő hatókörök; }Ezek szinkronizálódnak az alkalmazásunkban ténylegesen definiált hatókörökkel a / foos API.
10.3. SecurityContext
Végül meg kell határoznunk a SecurityContext az API példánkhoz:
privát SecurityContext securityContext () {return SecurityContext.builder () .securityReferences (Arrays.asList (new SecurityReference ("spring_oauth", hatókörök ()))) .forPaths (PathSelectors.regex ("/ foos. *")) .build ( ); }Vegye figyelembe, hogy az itt használt név a referenciában - tavaszi_autó - szinkronizálódik azzal a névvel, amelyet korábban a SecurityScheme.
10.4. Teszt
Most, hogy mindent beállítottunk és készen állunk az indulásra, vessünk egy pillantást a Swagger felhasználói felületünkre, és próbáljuk meg elérni a Foo API-t.
Helyileg elérhetjük a Swagger felhasználói felületet:
//localhost:8082/spring-security-oauth-resource/swagger-ui.htmlMint láthatjuk, a biztonsági konfigurációink miatt most már létezik egy új Engedélyezés gomb:
Amikor az Engedélyezés gombra kattintunk, a következő felugró ablakban láthatjuk, hogy a Swagger kezelőfelületünket engedélyezzük a biztonságos API eléréséhez:
Vegye figyelembe, hogy:
- Már láthatjuk a CLIENT_ID és a CLIENT_SECRET elemeket, mivel korábban előre konfiguráltuk őket (de még mindig módosíthatjuk őket).
- Most kiválaszthatjuk a szükséges hatóköröket.
Így jelölik a biztonságos API-t:
És most végre elérhetjük az API-t!
Természetesen szinte magától értetődik, hogy vigyáznunk kell arra, hogy a Swagger UI-t hogyan tesszük ki külsőleg, most, hogy ez a biztonsági konfiguráció aktív.
11. Következtetés
Ebben a cikkben a Swagger 2-t állítottuk be a Spring REST API dokumentációjának előállításához. Megvizsgáltuk a Swagger kimenetének vizualizálásának és testreszabásának módjait is. És végül megnéztük a Swagger egyszerű OAuth konfigurációját.
A teljes végrehajtása az oktatóanyag a GitHub projektben található. Ha meg szeretné tekinteni a Boot projekt beállításait, nézze meg ezt a GitHub modult.
Az OAuth szakaszhoz a kód a spring-security-oauth adattárunkban érhető el.
Ha pedig a REST With Spring hallgatója, akkor ugorjon a 7. modul 1. leckéjére, ahol mélyen elmerülhet a Swagger beállítása tavasszal és tavasszal indítással.
Biztonsági alsó
