关于java:Swagger官方Starter

之前我的项目中整合Swagger都是间接通过依赖springfox-swagger、springfox-swagger-ui两个jar包来实现的，最近发现springfox 3.0.0版本曾经有了本人的SpringBoot Starter，应用起来更符合SpringBoot我的项目，十分不便，举荐给大家！

应用官网Starter

咱们先应用官网Starter来整合Swagger看看是否够简略！

首先在pom.xml中增加springfox官网Swagger依赖；

<dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-boot-starter</artifactId>    <version>3.0.0</version></dependency>

增加Swagger的Java配置，配置好Api信息和须要生成接口文档的类扫描门路即可；

/** * Swagger2API文档的配置 */@Configurationpublic class Swagger2Config {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("com.mybatis.plus"))                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("SwaggerUI演示")                .description("Spring Boot Swagger2 构建把把智能")                .contact(new Contact("wlb", null, null))                .version("1.0")                .build();    }}

注：这里不再须要 @EnableSwagger2注解

拜访API文档信息，拜访地址：http://localhost:8080/swagger-ui/

两步即可搞定SpringBoot集成Swagger，是不是很简略！

与之前版本相比

之前咱们应用的是springfox 2.9.2版本，接下来比照下3.0.0的SpringBoot Starter应用，看看有何不同！

旧版本须要依赖springfox-swagger2和springfox-swagger-ui两个配置，新版本一个Starter就搞定了，而且之前的版本如果不应用新版本的swagger-models和swagger-annotations依赖，拜访接口会呈现NumberFormatException问题；

<dependencies>    <dependency>        <groupId>io.springfox</groupId>        <artifactId>springfox-swagger2</artifactId>        <exclusions>            <exclusion>                <groupId>io.swagger</groupId>                <artifactId>swagger-annotations</artifactId>            </exclusion>            <exclusion>                <groupId>io.swagger</groupId>                <artifactId>swagger-models</artifactId>            </exclusion>        </exclusions>    </dependency>    <dependency>        <groupId>io.springfox</groupId>        <artifactId>springfox-swagger-ui</artifactId>    </dependency>    <!--解决Swagger 2.9.2版本NumberFormatException-->    <dependency>        <groupId>io.swagger</groupId>        <artifactId>swagger-models</artifactId>        <version>1.6.0</version>    </dependency>    <dependency>        <groupId>io.swagger</groupId>        <artifactId>swagger-annotations</artifactId>        <version>1.6.0</version>    </dependency></dependencies>

新版本去除了一些第三方依赖，包含guava，之前应用旧版本时就因为guava版本问题导致过依赖抵触，具体能够看下《给Swagger降级了新版本，没想到竟然有这么多坑！》；
新版本和旧版本文档拜访门路产生了变动，新版本为：http://localhost:8080/swagger-ui/ ，旧版本为：http://localhost:8080/swagger-ui.html
新版本中新增了一些SpringBoot配置，springfox.documentation.enabled配置能够管制是否启用Swagger文档生成性能；
比如说咱们只想在dev环境下启用Swagger文档，而在prod环境下不想启用，旧版本咱们能够通过@Profile注解实现；

@Configuration@EnableSwagger2@Profile(value = {"dev"})public class Swagger2Config {    }

新版本咱们在SpringBoot配置文件中进行配置即可，springfox.documentation.enabled在application-dev.yml配置为true，在application-prod.yml中配置为false。

整合Spring Security应用

咱们常常会在我的项目中应用Spring Security实现登录认证，接下来咱们来讲下如何应用Swagger整合Spring Security，实现拜访须要登录认证的接口。

如何拜访须要登录认证的接口？只需在拜访接口时增加一个非法的Authorization申请头即可，上面是Swagger相干配置；

/** * Swagger2API文档的配置 */@Configurationpublic class Swagger2Config {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("com.mybatis.plus"))                .paths(PathSelectors.any())                .build()                //增加登录认证                .securitySchemes(securitySchemes())                .securityContexts(securityContexts());    }     //构建 api文档的详细信息函数 private ApiInfo apiInfo() {        return new ApiInfoBuilder()                //页面题目        .title("Spring Boot Swagger2 构建把把智能")         //条款地址        .termsOfServiceUrl("http://despairyoke.github.io/")        .contact(new Contact("wlb", null, null))        .version("1.0")        //形容        .description("API 形容")        .build(); }    private List<SecurityScheme> securitySchemes() {        //设置申请头信息        List<SecurityScheme> result = new ArrayList<>();        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");        result.add(apiKey);        return result;    }    private List<SecurityContext> securityContexts() {        //设置须要登录认证的门路        List<SecurityContext> result = new ArrayList<>();        result.add(getContextByPath("/brand/.*"));        return result;    }    private SecurityContext getContextByPath(String pathRegex) {        return SecurityContext.builder()                .securityReferences(defaultAuth())                .forPaths(PathSelectors.regex(pathRegex))                .build();    }    private List<SecurityReference> defaultAuth() {        List<SecurityReference> result = new ArrayList<>();        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];        authorizationScopes[0] = authorizationScope;        result.add(new SecurityReference("Authorization", authorizationScopes));        return result;    }}

咱们须要在Spring Security中配置好Swagger动态资源的无受权拜访，比方首页拜访门路/swagger-ui/；

package com.spring.security.demo.config;import com.spring.security.demo.security.JwtAuthenticationFilter;import com.spring.security.demo.security.JwtAuthenticationProvider;import com.spring.security.demo.security.JwtLoginFilter;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.http.HttpMethod;import org.springframework.security.authentication.AuthenticationManager;import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;import org.springframework.security.config.annotation.method.configuration.EnableGlobalMethodSecurity;import org.springframework.security.config.annotation.web.builders.HttpSecurity;import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;import org.springframework.security.core.userdetails.UserDetailsService;import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;import org.springframework.security.web.authentication.logout.HttpStatusReturningLogoutSuccessHandler;@Configuration@EnableWebSecurity@EnableGlobalMethodSecurity(prePostEnabled = true)/** * 对SpringSecurity的配置的扩大，反对自定义白名单资源门路和查问用户逻辑 */public class SecurityConfig extends WebSecurityConfigurerAdapter {    @Autowired private UserDetailsService userDetailsService; @Override public void configure(AuthenticationManagerBuilder auth) throws Exception {        // 如果间接定制UserDetailsService ，而不自定义 AuthenticationProvider，能够间接在配置文件 WebSecurityConfig 中这样配置。 // 指定自定义的获取信息获取服务//        auth.userDetailsService(userDetailsService); // 应用自定义登录身份认证组件----> 指定了自定义身份认证组件 JwtAuthenticationProvider，并注入 UserDetailsService auth.authenticationProvider(new JwtAuthenticationProvider(userDetailsService)); }    @Override protected void configure(HttpSecurity http) throws Exception {    // 禁用 csrf, 因为应用的是JWT，咱们这里不须要csrf    http.cors().and().csrf()        .disable()        .sessionManagement()// 基于token，所以不须要session    .sessionCreationPolicy(SessionCreationPolicy.STATELESS)        .and()        .authorizeRequests()        .antMatchers(HttpMethod.GET, // 容许对于网站动态资源的无受权拜访                "/",                "/swagger-ui/",                "/*.html",                "/favicon.ico",                "/**/*.html",                "/**/*.css",                "/**/*.js",                "/swagger-resources/**",                "/v2/api-docs/**"        )        .permitAll()        .antMatchers("/login")// 对登录注册要容许匿名拜访        .permitAll()       .antMatchers(HttpMethod.OPTIONS)//跨域申请会先进行一次options申请        .permitAll()        .anyRequest()// 除下面外的所有申请全副须要鉴权认证        .authenticated();         // 退出登录处理器         http.logout().logoutSuccessHandler(new             HttpStatusReturningLogoutSuccessHandler()); // 开启登录认证流程过滤器----> 指定了登录认证流程过滤器 JwtLoginFilter，由它来触发登录认证//        http.addFilterBefore(new JwtLoginFilter(authenticationManager()), UsernamePasswordAuthenticationFilter.class); // 访问控制时登录状态查看过滤器----> 指定了访问控制过滤器 JwtAuthenticationFilter，在受权时解析令牌和设置登录状态 http.addFilterBefore(new JwtAuthenticationFilter(authenticationManager()), UsernamePasswordAuthenticationFilter.class); }    //初始化authenticationManager @Bean @Override public AuthenticationManager authenticationManager() throws Exception {        return super.authenticationManager(); }}

调用登录接口获取token，账号密码为admin:123456；
点击Authorize按钮后输出Authorization申请头，之后就能够拜访须要登录认证的接口了。

总结

Swagger官网Starter解决了之前整合Swagger的一系列问题，简化了SpringBoot整合Swagger的过程，应用起来更加不便了。同时对于一些简单的配置应用根本没有变动，一些之前的应用形式仍然能够应用！