Nastavenie Swagger 2 pomocou Spring REST API
Práve som oznámil nový kurz Learn Spring Security vrátane úplného materiálu zameraného na nový zásobník OAuth2 vo Spring Security 5:
>> SKONTROLUJTE KURZ ODPOČINOK NajlepšiePráve som oznámil nové Naučte sa jar kurz zameraný na základy jari 5 a Spring Boot 2:
>> SKONTROLUJTE KURZ1. Prehľad
V dnešnej dobe front-end a back-end komponenty často oddeľujú webovú aplikáciu. Zvyčajne vystavujeme API ako back-endový komponent pre front-endový komponent alebo integráciu aplikácií tretích strán.
V takomto scenári je nevyhnutné mať správne špecifikácie pre back-end API. Dokumentácia k API by mala byť zároveň informatívna, čitateľná a ľahko čitateľná.
Referenčná dokumentácia by mala navyše súčasne popisovať všetky zmeny v API. Ručné vykonávanie tohto postupu je zdĺhavé, takže automatizácia procesu bola nevyhnutná.
V tomto návode sa pozrieme na Swagger 2 pre webovú službu Spring RESTpomocou implementácie Springfoxu špecifikácie Swagger 2.
Ak nie ste oboznámení s programom Swagger, navštívte jeho webovú stránku, kde sa dozviete viac, skôr ako budete pokračovať v tejto príručke.
2. Cieľový projekt
Vytvorenie služby REST, ktorú použijeme, nespadá do rozsahu tohto článku. Ak už máte vhodný projekt, využite ho. Ak nie, tieto odkazy sú dobrým miestom na začatie:
- Vytvorte si REST API s článkom Spring 4 a Java Config
- Budovanie RESTful webovej služby
3. Pridanie závislosti Maven
Ako už bolo spomenuté vyššie, použijeme Springfox implementáciu špecifikácie Swagger. Najnovšiu verziu nájdete na serveri Maven Central.
Aby sme to mohli pridať do nášho projektu Maven, potrebujeme závislosť v pom.xml spis:
io.springfox springfox-swagger2 2.9.2 3.1. Závislosť jarného zavedenia
Pre projekty založené na jarnom zavedení stačí pridať jediný springfox-boot-starter závislosť:
io.springfox springfox-boot-starter 3.0.0 4. Integrácia Swagger 2 do projektu
4.1. Konfigurácia Java
Konfigurácia Swagger sa sústreďuje hlavne okolo Docket fazuľa:
@Configuration verejná trieda SpringFoxConfig {@Bean public Docket api () {vrátiť nový Docket (DocumentationType.SWAGGER_2) .select () .apis (RequestHandlerSelectors.any ()) .paths (PathSelectors.any ()) .build (); }}Po definovaní Docket fazuľa, jej vyberte () metóda vracia inštanciu ApiSelectorBuilder, ktorý poskytuje spôsob kontroly koncových bodov vystavených Swaggerovi.
Môžeme nakonfigurovať predikáty pre výber RequestHandlers pomocou RequestHandlerSelectors a PathSelectors. Použitím akýkoľvek() pretože obidve sprístupnia dokumentáciu pre celé naše API prostredníctvom aplikácie Swagger.
4.2. Konfigurácia bez Spring Boot
V jednoduchých jarných projektoch musíme Swagger 2 výslovne povoliť. Urobiť tak, musíme použiť @ EnableSwagger2WebMvc na našej konfiguračnej triede:
@Configuration @ EnableSwagger2WebMvc verejná trieda SpringFoxConfig {}Navyše bez Spring Boot nemáme luxus automatickej konfigurácie našich prostriedkov na spracovanie zdrojov.
Swagger UI pridáva množinu zdrojov, ktoré musíme nakonfigurovať ako súčasť rozširujúcej sa triedy WebMvcConfigurerAdapter a je označený poznámkou @EnableWebMvc:
@Override public void addResourceHandlers (register ResourceHandlerRegistry) {registry.addResourceHandler ("swagger-ui.html") .addResourceLocations ("classpath: / META-INF / resources /"); registry.addResourceHandler ("/ webjars / **") .addResourceLocations ("classpath: / META-INF / resources / webjars /"); }4.3. Overenie
Aby sme overili, že Springfox funguje, môžeme v našom prehliadači navštíviť túto adresu URL:
// localhost: 8080 / spring-security-rest / api / v2 / api-docs
Výsledkom je odpoveď JSON s veľkým počtom párov kľúč - hodnota, ktorá nie je veľmi dobre čitateľná. Našťastie Swagger poskytuje Swagger UI pre tento účel.
5. Swagger UI
Swagger UI je zabudované riešenie, ktoré výrazne uľahčuje interakciu používateľa s dokumentáciou API generovanou Swaggerom.
5.1. Povolenie používateľského rozhrania Springfox's Swagger
Ak chcete používať používateľské rozhranie Swagger, musíme pridať ďalšiu závislosť Maven:
io.springfox springfox-swagger-ui 2.9.2 Teraz to môžeme otestovať v našom prehliadači po návšteve:
// localhost: 8080 / your-app-root / swagger-ui /
V našom prípade bude mimochodom presná adresa URL:
// localhost: 8080 / spring-security-rest / api / swagger-ui /
Výsledok by mal vyzerať asi takto:
5.2. Skúmanie dokumentácie Swagger
V rámci Swaggerovej odpovede je zoznam všetkých radičov definované v našej aplikácii. Kliknutím na niektorú z nich sa zobrazí zoznam platných metód HTTP (ODSTRÁNIŤ, ZÍSKAJTE, HLAVA, MOŽNOSTI, PATCH, POST, PUT).
Rozšírenie každej metódy poskytuje ďalšie užitočné údaje, ako napríklad stav odozvy, typ obsahu a zoznam parametrov. Je tiež možné vyskúšať každú metódu pomocou používateľského rozhrania.
Schopnosť Swaggera byť synchronizovaný s našou kódovou základňou je zásadná. Aby sme to demonštrovali, môžeme do našej aplikácie pridať nový radič:
@RestController verejná trieda CustomController {@RequestMapping (value = "/ custom", method = RequestMethod.POST) public String custom () {return "custom"; }}Teraz, keď obnovíme dokumentáciu Swagger, uvidíme custom-controller v zozname radičov. Ako vieme, existuje iba jedna metóda (POST) zobrazené v Swaggerovej odpovedi.
6. Jarné údaje REST
Springfox poskytuje podporu pre Spring Data REST prostredníctvom svojho springfox-data-rest knižnica.
Spring Boot sa postará o automatickú konfiguráciu, ak objaví spring-boot-starter-data-rest na triednej ceste.
Teraz vytvorme entitu s názvom Používateľ:
@Entity public class Užívateľ {@Id private Long id; private String meno; súkromný int vek; súkromný reťazcový e-mail; // zakladatelia a zakladatelia}Potom vytvoríme UserRepository pridať operácie CRUD na Používateľ subjekt:
@Repository verejné rozhranie UserRepository rozširuje CrudRepository {}Nakoniec importujeme SpringDataRestConfiguration triedy do SpringFoxConfig trieda:
@ EnableSwagger2WebMvc @Import (SpringDataRestConfiguration.class) verejná trieda SpringFoxConfig {// ...}Poznámka: Použili sme @ EnableSwagger2WebMvc anotácia, aby umožnila Swagger, pretože nahradila @ EnableSwagger2 anotácia vo verzii 3 knižníc.
Poďme reštartovať aplikáciu a vygenerovať špecifikácie pre API Spring Data REST:
Vidíme, že Springfox vygeneroval špecifikácie pre Používateľ entita s metódami HTTP ako ZÍSKAJTE, POST, PUT, PATCH, a ODSTRÁNIŤ.
7. Overenie fazule
Springfox tiež podporuje anotácie fazule prostredníctvom svojich springfox-bean-validátory knižnica.
Najskôr do našej pridáme závislosť Maven pom.xml:
io.springfox springfox-bean-validátory 2.9.2 Opäť ak použijeme Spring Boot, nemusíme vyššie uvedenú závislosť výslovne uvádzať.
Ďalej pridáme niekoľko overovacích anotácií ako @NotNull a @ Min do Používateľ subjekt:
@Entity verejná trieda Používateľ {// ... @NotNull (message = "Krstné meno nemôže byť null") súkromný reťazec krstné meno; @Min (hodnota = 15, message = "Vek by nemal byť menší ako 15") @Max (hodnota = 65, message = "Vek by nemal byť väčší ako 65") súkromný vek; }Nakoniec importujeme BeanValidatorPluginsConfiguration triedy do SpringFoxConfig trieda:
@ EnableSwagger2 @Import (BeanValidatorPluginsConfiguration.class) verejná trieda SpringFoxConfig {// ...}Pozrime sa na zmeny v špecifikáciách API:
Tu môžeme pozorovať, že Používateľ model má * požadovaný na krstné meno. Tiež minimum a maximálne hodnoty sú definované pre Vek.
8. Plugin
Aby sme mohli do špecifikácií API pridať konkrétne funkcie, môžeme vytvoriť doplnok Springfox. Doplnok môže ponúkať rôzne funkcie, od obohatenia modelov a vlastností až po vlastné výpisy a predvolené hodnoty API.
Springfox podporuje vytváranie pluginov prostredníctvom svojho spi modulu. Modul spi poskytuje niekoľko rozhraní ako ModelBuilderPlugin, ModelPropertyBuilderPlugina ApiListingBuilderPlugin ktoré fungujú ako hák rozšíriteľnosti pri implementácii vlastného doplnku.
Aby sme demonštrovali tieto schopnosti, vytvorme si doplnok, ktorý obohatí e-mail majetok Používateľ Model. Použijeme ModelPropertyBuilderPlugin rozhranie a nastaviť hodnoty vzor a príklad.
Najskôr vytvorme EmailAnnotationPlugin triedy a prepísať podporuje metóda umožňujúca akýkoľvek typ dokumentácie, napríklad Swagger 1.2 a Swagger 2:
@Component @Order (Validators.BEAN_VALIDATOR_PLUGIN_ORDER) verejná trieda EmailAnnotationPlugin implementuje ModelPropertyBuilderPlugin {@Override public boolean supports (DocumentationType delimiter) {return true; }}Potom prepíšeme uplatniť metóda ModelPropertyBuilderPlugin nastavenie hodnôt vlastností staviteľa:
@Override public void apply (ModelPropertyContext context) {Voliteľný email = annotationFromBean (kontext, Email.class); if (email.isPresent ()) {context.getSpecificationBuilder (). facetBuilder (StringElementFacetBuilder.class) .pattern (email.get (). regexp ()); context.getSpecificationBuilder (). example ("[chránený e-mailom]"); }}Špecifikácie API teda ukážu vzor a príklad hodnoty nehnuteľnosti anotované s @Email anotácia.
Ďalej pridáme @Email anotácia k Používateľ subjekt:
@Entity verejná trieda Používateľ {// ... @Email (regexp = ". * @. * \ .. *", message = "E-mail by mal byť platný") súkromný reťazcový e-mail; }Nakoniec povolíme EmailAnnotationPlugin v SpringFoxConfig triedy registráciou ako fazuľa:
@Import ({BeanValidatorPluginsConfiguration.class}) verejná trieda SpringFoxConfig {// ... @Bean public EmailAnnotationPlugin emailPlugin () {return new EmailAnnotationPlugin (); }}Poďme sa pozrieť na EmailAnnotationPlugin v akcii:
Môžeme vidieť hodnotu vzor je rovnaký regulárny výraz (. * @. * \ .. *) z e-mail majetok Používateľ subjekt.
Podobne aj hodnota príklad ([chránený e-mailom]) je rovnaký, ako je definované v uplatniť metóda EmailAnnotationPlugin.
9. Pokročilá konfigurácia
The Docket fazuľa našej aplikácie môže byť nakonfigurovaná tak, aby nám poskytla väčšiu kontrolu nad procesom generovania dokumentácie API.
9.1. Filtrovanie API pre odpoveď Swagger’s
Nie je vždy žiaduce sprístupniť dokumentáciu pre celé API. Môžeme obmedziť Swaggerovu reakciu odovzdaním parametrov do apis () a cesty () metódy Docket trieda.
Ako je vidieť vyššie, RequestHandlerSelectors umožňuje použitie akýkoľvek alebo žiadny predikáty, ale je možné ich použiť aj na filtrovanie API podľa základného balíka, anotácií tried a anotácií metód.
PathSelectors poskytuje ďalšie filtrovanie s predikátmi, ktoré skenujú cesty požiadaviek našej aplikácie. Môžeme použiť akýkoľvek(), žiadny (), regulárny výraz ()alebo mravec ().
V nižšie uvedenom príklade budeme inštruovať Swagger, aby používal iba radiče z konkrétneho balíka so špecifickými cestami, ktoré používajú mravec () prísudok:
@Bean public Docket api () {vrátiť nový Docket (DocumentationType.SWAGGER_2) .select () .apis (RequestHandlerSelectors.basePackage ("com.baeldung.web.controller")) .paths (PathSelectors.ant ("/ foos / *) ")) .build (); }9.2. Vlastné informácie
Swagger vo svojej odpovedi poskytuje aj niektoré predvolené hodnoty, ktoré môžeme prispôsobiť, napríklad „Dokumentácia Api“, „Vytvorené kontaktným e-mailom“ a „Apache 2.0“.
Na zmenu týchto hodnôt môžeme použiť apiInfo (ApiInfo apiInfo) metóda - ApiInfo trieda, ktorá obsahuje vlastné informácie o API:
@Bean public Docket api () {vrátiť nový 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", "Some custom description of API.", "API TOS", "Terms of service", new Contact ("John Doe", "www.example. com "," [chránené e-mailom] ")," Licencia API "," URL licencie API ", Collections.emptyList ()); }9.3. Správy s odpoveďou na vlastné metódy
Swagger umožňuje globálne prednostné správy s odpoveďou metód HTTP cez Docket‘S globalResponseMessage ()metóda.
Najprv musíme dať Swaggerovi pokyn, aby nepoužíval predvolené správy s odpoveďou. Predpokladajme, že chceme prepísať 500 a 403 správy s odpoveďou pre všetkých ZÍSKAJTE metódy.
Aby ste to dosiahli, je potrebné do kódu pridať nejaký kód DocketInicializačný blok (kvôli jasnosti je pôvodný kód vylúčený):
.useDefaultResponseMessages (false) .globalResponseMessage (RequestMethod.GET, newArrayList (nový ResponseMessageBuilder () .code (500) .message ("500 správa") .responseModel (nový ModelRef ("chyba")) .build (), nový ResponseMessage ) .kód (403) .message („Zakázané!“) .build ()));
10. Napätie používateľského rozhrania s OAuth-Secured API
Swagger UI poskytuje množstvo veľmi užitočných funkcií, ktoré sme tu doteraz dobre pokryli. Ale väčšinu z nich nemôžeme skutočne použiť, ak je naše API zabezpečené a neprístupné.
Pozrime sa, ako môžeme v tomto príklade povoliť Swaggerovi prístup k API zabezpečenému OAuth pomocou typu grantu Autorizačný kód.
Nakonfigurujeme Swagger na prístup k nášmu zabezpečenému API pomocou Bezpečnostná schéma a SecurityContext podpora:
@Bean public Docket api () {vrátiť nový Docket (DocumentationType.SWAGGER_2) .select () .apis (RequestHandlerSelectors.any ()) .paths (PathSelectors.any ()) .build () .securitySchemes (Arrays.asList (securityScheme) ())) .securityContexts (Arrays.asList (securityContext ())); }10.1. Konfigurácia zabezpečenia
Definujeme a SecurityConfiguration fazuľa v našej konfigurácii Swagger a nastaviť niektoré predvolené hodnoty:
@Bean public SecurityConfiguration security () {return SecurityConfigurationBuilder.builder () .clientId (CLIENT_ID) .clientSecret (CLIENT_SECRET) .scopeSeparator ("") .useBasicAuthenticationWithAccessCodeGrant (true) .build (); }10.2. Bezpečnostná schéma
Ďalej definujeme naše Bezpečnostná schéma; toto sa používa na opis zabezpečenia nášho rozhrania API (základné overenie, OAuth2, ...).
V našom prípade tu definujeme schému OAuth použitú na zabezpečenie nášho servera zdrojov:
private SecurityScheme securityScheme () {GrantType grantType = new AuthorizationCodeGrantBuilder () .tokenEndpoint (new TokenEndpoint (AUTH_SERVER + "/ token", "oauthtoken")) .tokenRequestEndpoint (new TokenRequestEndpoint (AUTH_SERVER +) "AUTH_SERVER" build (); SecurityScheme oauth = nový OAuthBuilder (). Name ("spring_oauth") .grantTypes (Arrays.asList (grantType)) .scopes (Arrays.asList (scopes ())) .build (); návrat oauth; }Upozorňujeme, že sme použili typ udelenia autorizačného kódu, pre ktorý musíme poskytnúť koncový bod tokenu a autorizačnú adresu URL nášho autorizačného servera OAuth2.
A tu sú rozsahy, ktoré musíme mať definované:
private AuthorizationScope [] scopes () {AuthorizationScope [] scopes = {new AuthorizationScope ("read", "for read operations"), new AuthorizationScope ("write", "for write operations"), new AuthorizationScope ("foo", " Access foo API ")}; spätné rozsahy; }Tieto sa synchronizujú s rozsahmi, ktoré sme v skutočnosti definovali v našej aplikácii pre / foos API.
10.3. SecurityContext
Nakoniec musíme definovať a SecurityContext pre náš príklad API:
private SecurityContext securityContext () {return SecurityContext.builder () .securityReferences (Arrays.asList (new SecurityReference ("spring_oauth", scopes ()))) .forPaths (PathSelectors.regex ("/ foos. *")) .build ( ); }Všimnite si, ako názov, ktorý sme tu použili v referencii - spring_oauth - synchronizuje sa s menom, ktoré sme predtým používali v Bezpečnostná schéma.
10.4. Test
Teraz, keď máme všetko nastavené a pripravené na použitie, sa pozrime na naše používateľské rozhranie Swagger a skúsme získať prístup k rozhraniu Foo API.
K používateľskému rozhraniu Swagger môžeme pristupovať lokálne:
//localhost:8082/spring-security-oauth-resource/swagger-ui.htmlAko vidíme, nové tlačidlo Autorizovať teraz existuje z dôvodu našich bezpečnostných konfigurácií:
Keď klikneme na tlačidlo Autorizovať, zobrazí sa nasledujúce vyskakovacie okno, ktoré autorizuje naše používateľské rozhranie Swagger na prístup k zabezpečenému rozhraniu API:
Poznač si to:
- CLIENT_ID a CLIENT_SECRET už vidíme, pretože sme ich predtým nakonfigurovali skôr (stále ich však môžeme zmeniť).
- Teraz môžeme vybrať rozsahy, ktoré potrebujeme.
Takto je označené zabezpečené API:
A teraz konečne môžeme naraziť na naše API!
Samozrejme, je takmer samozrejmé, že musíme byť opatrní, ako externe vystavujeme používateľské rozhranie Swagger, keď je teraz táto konfigurácia zabezpečenia aktívna.
11. Záver
V tomto článku sme nastavili program Swagger 2 na generovanie dokumentácie pre Spring REST API. Preskúmali sme tiež spôsoby vizualizácie a prispôsobenia výstupu Swagger. A nakoniec sme sa pozreli na jednoduchú konfiguráciu OAuth pre Swagger.
The úplná implementácia tohto tutoriálu nájdete v projekte GitHub. Ak si chcete pozrieť nastavenie v bootovacom projekte, vyskúšajte tento modul GitHub.
Pre sekciu OAuth je kód k dispozícii v našom úložisku spring-security-oauth.
A ak ste študentom programu REST With Spring, choďte na lekciu 1 z modulu 7, kde sa podrobne ponorte do nastavenia aplikácie Swagger with Spring and Spring Boot.
Bezpečnostné dno
