前言

如何在springboot+security项目上部署swagger2 ，并遇到请求拦截问题的解决

一、swagger2是什么？

Swagger2是

可以快速生成RESTful API 文档框架，

可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：

1. 接口文档在线自动生成，文档随接口变动实时更新，节省维护成本

2. 支持在线接口测试，不依赖第三方工具

二、使用步骤

1.springboot集成swagger，在pom.xml上添加依赖

代码如下（示例）：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <!--swagger ui 默认模板-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

2.创建Swagger2Config配置文件

代码如下（示例）：

@Configuration
@EnableSwagger2  //启动配置类
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        ticketPar.name("Authorization").description("user ticket")//Token 以及Authorization 为自定义的参数，session保存的名字是哪个就可以写成那个
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build(); //header中的ticket参数非必填，传空也可以
        pars.add(ticketPar.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.crazyread.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("疯狂阅读接口文档 RESTful APIs")
                .description("ks wms RESTful APIs")
                .termsOfServiceUrl("http://localhost:80/crazyread/doc.html")
                .version("1.0")
                .build();
    }

}

如果你项目使用了security那么你所有请求都会被拦截，需要你登陆时生成的token验证才能请求成

3.最后在controller类中配置对应注释

代码如下（示例）：

RestController
@RequestMapping("/user")
@Api(value = "用户管理 controller" ,tags = {"用户管理接口统计"})
public class AdminController {
    @Autowired
    UserMapper userMapper;
    @Autowired
    UserServiceImpl userService;
    @Autowired
    UserAuthorityMapper userAuthorityMapper;
    @Autowired
    UserDetailsServiceImpl userDetailsService;



    /**
     * 获取用户信息接口
     * @param principal
     * @return
     */
    @GetMapping("/userInfo")
    @ApiOperation(value = "获取用户信息接口")
    public Result userInfo(Principal principal){
        User user = userMapper.selUserByUsername(principal.getName());
        return Result.succ(MapUtil.builder()
                .put("id", user.getId())
                .put("username", user.getUsername())
                .put("email", user.getEmail())
                .put("created", user.getCreated())
                .map()
        );
    }
}

启动项目成功后，打开

http://localhost/swagger-ui.html

，但是你会发现页面显示空白它需要你登陆

这是因为你在springboot使用security，它会对所有请求接口拦截，你需要登录拿到token做一个验证，如果每次使用接口都要请求就很麻烦。所以可以在securityconfig配置下 设置免请求如下：

             // 配置拦截规则
                .and()
                .authorizeRequests()
                .antMatchers( "/swagger-ui.html",
                        "/v2/**",
                        "/swagger-resources/**",
                        "/webjars/springfox-swagger-ui/**").permitAll()
                .anyRequest().authenticated()

然后再次打开 http://localhost/swagger-ui.html，就能看见在线文档了

效果