springboot整合swagger

公司目前尚未提供在api文档，前后端分离的项目，需要后端手动维护api文档，来帮助前端完成正常的功能联调测试等工作。但是目前公司的项目，后端接口需要通过postman来完成，而且手动维护api文档，徒增后端开发人员的时间成本，而且手动维护出错概率大，会造成前后端时间成本增加。借鉴上家公司的方案，希望改善这一部分的不足。关于前后端分离项目，业内普遍采用的都是利用swagger实现在线api文档，减少沟通维护的时间成本。

springboot整合swagger步骤如下

#引入基础jar包
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.8.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.8.0</version>
    </dependency>

添加swagger配置文件，并在项目中启用swagger

@Configuration
@EnableSwagger2
@Profile("dev")
public class Swagger2Config {
   @Bean
   public Docket createRestApi() {
       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
               .paths(PathSelectors.any())
               .build()
               .enable(!Util.runEvn.equals(AppServer.Type.prod.name()));
   }
   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("xxxxx项目 RESTful APIs")
               .description("xxxxx项目后台api接口文档")
               .version("1.0")
               .build();
   }
}

配置js，css等前端文件路径问题，如果项目中使用权限拦截，一并对swagger放行

@Configuration
public class AppMvcConfigurer extends WebMvcConfigurerAdapter {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    // 增加拦截器
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        super.addInterceptors(registry);
        registry.addInterceptor(new RequestHandlerInterceptor()).addPathPatterns("/**");
        registry.addInterceptor(tokenAndPermissionAndDrInterceptor).addPathPatterns("/**/*")
                .excludePathPatterns("/swagger-ui.html", "/swagger-resources/**", "/v2/**", "/error/**" //);添加swagger exclude;
        registry.addInterceptor(headerInterceptor).addPathPatterns("/**");
    }
}

注意在controller类中添加swagger相关注解，如果扫描不到一样无法正常使用的。例如

@Api(value = "TestController", description = "用户登录登出接口")
@RestController
@Slf4j
@RequestMapping(value = "/api/test")
public class TestController {
    @Resource
    private UserLoginService userLoginService;
    @ApiOperation(value="用户登录", notes="用户登录接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "email", value = "邮箱", required = true ,dataType = "string"),
            @ApiImplicitParam(name = "password", value = "密码", required = true ,dataType = "string")
    })
    @RequestMapping (value = "/login",method = RequestMethod.GET)
    @ResponseBody
    public JsonData userLogin(@RequestParam String email,@RequestParam String password){
        UserParam user = new UserParam();
        user.setEmail(email);
        user.setPassword(password);
        log.info("login parameter:{}", JsonUtil.toJson(user));
        JsonData jsonData = null;
        try {
            BeanValidatorUtil.validateParam(user);
            jsonData =  userLoginService.login(user);
        } catch (ParamException e) {
            return JsonData.error(e.getMessage());
        } catch (Exception e) {
            log.error("login failure,error:", e);
            return JsonData.error("登录异常，请联系管理员查看。");
        }
        log.info("login ret:{}", JsonUtil.toJson(jsonData));
        return jsonData;
    }

正常的流程，swagger配置这些内容之后，在项目启动之后在当前的启动路径后拼接/swagger-ui.html即可看到正常swagger界面，如下

但是一般好事都会多磨！！！

之前小编正常配置这些内容后，swagger的界面依旧不能正常显示，提示错误内容如下

    这种错误一般分为两种情况，一种swagger配置内容有问题，怎么判断是否swagger有问题呢？判断http://localhost:8081/xxx/v2/api-docs 是否有api接口，如果有，则证明swagger配置没有问题；另外一种就是项目中某些拦截器或者过滤器将swagger的项目内容处理了，不能得到正常的响应。

小编遇到就是第二种错误，经过一系列的排查发现是EmojiEncodingFilter过滤器将swagger相关的内容都过滤了，所以造成相关js不能正常响应。

swagger-ui-layer使用

但是小编在这个过程也发现了新大陆，就是swagger-ui-layer，一个替代原生swagger-ui的好看UI界面

相比不习惯swagger-ui的这个可能是福利吧。

开源地址：​​https://github.com/caspar-chen/swagger-ui-layer​​ 使用方式，上述地址均有介绍。

既然发现了彩蛋不能不利用啊，所以我目前的项目中兼具swagger-ui和swagger-ui-layer 开发人员可以根据自己的喜好选择前端页面了哈。

  <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.8.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.8.0</version>
    </dependency>
    <dependency>
        <groupId>com.github.caspar-chen</groupId>
        <artifactId>swagger-ui-layer</artifactId>
        <version>1.1.1</version>
    </dependency>

总结

在整合的过程，遇到js丢失的问题，花费的时间比较长，其中主要原因是java知识不扎实，考虑到拦截器可能会造成js丢失，却忽略过滤器也会带来同样的问题。还是提升自己吧。最后感触比较深的一个点，做事要靠信念，只要相信，所有问题都会迎刃而解的。
ps：swagger在线上环境使用是不安全的，因为所有的api接口都对外暴露了，想要真正安全的使用，还需要配置maven的相关内容，达到根据环境配置决定是否启用。这一部分内容就放到之后的maven知识中讲解了。