swagger配置及升级版swagger-bootstrap-ui配置+访问账号密码登录限制

亲测可用

本文主要介绍swagger-ui及加强版swagger-bootstrap-ui配置

一：普通swagger-ui配置

1：pom添加依赖

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
1
2
3
4
5
6
7
8
9
10
11

2：添加配置类SwaggerConfig：

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.XXX.web.controller"))//扫描包范围
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * API 说明，包含作者、简介、版本、host、服务URL
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("XXXAPI文档")
                .description("XXXAPI文档")
                //.contact(new Contact("API文档", "http://www.XXX.com/", "xxx@qq.com"))//作者信息
                //.version("1.0")//定义api 版本号
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

3：如果有登录验证等拦截器，如下资源需要放行

@Component
public class MyInterceptorConfigure extends WebMvcConfigurationSupport { //WebMvcConfigurer

    @Autowired
    private MyInterceptor myInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {

        // excludePathPatterns 用户排除拦截
        String[] excludePathPatterns = { "/swagger-ui..html/**","/swagger-resources/**","/webjars/**","/v2/**"};
		registry.addInterceptor(userTokenInterceptor).addPathPatterns("/**").excludePathPatterns(excludePathPatterns);
        super.addInterceptors(registry);
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
  }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

4：Controller添加如下swagger 注解即可

controler类注解：
@Api(tags = "1.0",value = "auth",description = "授权登录Controller")

controler方法注解：
    @ApiOperation(value = "登录", notes = "用户登录",httpMethod = "POST")
    @ApiImplicitParam(name = "userId", value = "userId", required = true)
1
2
3
4
5
6

@Controller
@RequestMapping("auth")
@Api(tags = "1.0",value = "auth",description = "授权登录Controller")
public class LoginController {

    @ApiOperation(value = "登录", notes = "用户登录",httpMethod = "POST")
    @ApiImplicitParam(name = "userId", value = "userId", required = true)
    @RequestMapping("login")
    public String weChatAuth(Integer userId) {
1
2
3
4
5
6
7
8
9

5：访问地址

ip:port/swagger-ui.html
1

二：加强版swagger-bootstrap-ui配置

swagger-bootstrap-ui相比swagger-ui更加强大，提供测试及账号密码验证登录等配置，个人觉得文档页面样式更加简洁明了
配置方式基本与swagger-ui一致

1：修改pom依赖

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
1
2
3
4
5
6
7
8
9
10
11

2：添加配置类SwaggerConfig：在swagger-ui基础上只是多了@EnableSwaggerBootstrapUI类注解

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.XXX.web.controller"))//扫描包范围
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * API 说明，包含作者、简介、版本、host、服务URL
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("XXXAPI文档")
                .description("XXXAPI文档")
                //.contact(new Contact("API文档", "http://www.XXX.com/", "xxx@qq.com"))//作者信息
                //.version("1.0")//定义api 版本号
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

3：配置文件添加接口文档访问自定义账号密码（本文为yml格式）

#配置swagger登陆验证
swagger:
  production: false
  basic:
    enable: true
    username: xxx
    password: xxx
1
2
3
4
5
6
7

4：修改拦截器等放行资源

@Component
public class MyInterceptorConfigure extends WebMvcConfigurationSupport { //WebMvcConfigurer

    @Autowired
    private MyInterceptor myInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {

        // excludePathPatterns 用户排除拦截
        String[] excludePathPatterns = { "/doc.html/**","/swagger-resources/**","/webjars/**","/v2/**"};
		registry.addInterceptor(userTokenInterceptor).addPathPatterns("/**").excludePathPatterns(excludePathPatterns);
        super.addInterceptors(registry);
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
  }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

5：访问地址

ip:port/doc.html
账号密码即为3中所配置username及password
1
2