SpringBoot之整合Swagger2分析和实现-基于Spring Boot2.0.2版本

###概念介绍

• 随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
  前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。
  ###整合步骤
• 依赖导入

          
            io.springfox
            springfox-swagger2
            2.7.0
        
  
        
        
            io.springfox
            springfox-swagger-ui
            2.7.0
        
  

  • 添加SwaggerConfiguration

@Configuration
@EnableSwagger2// 必须加此注解
public class SwaggerConfiguration {

    @Autowired
    JWTConstant jwtConstant;

    @Bean
    public Docket createRestApi() {
        // jwt验证解决
        ParameterBuilder pb = new ParameterBuilder();
        List token = new ArrayList<>();
        pb.name(jwtConstant.JWT_HEADERS).description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        token.add(pb.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder().title("FrameWork 开发平台接口文档").description("Based On Spring Boot").termsOfServiceUrl("").version("1.0").build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cherry"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(token);
    }
}

• 在spring security的配置中对swagger的url进行放行
  在congiure的方法中添加如下例外路径

                 .antMatchers(serverPath + "/swagger-ui.html").permitAll()
                .antMatchers(serverPath + "/swagger-resources/**").permitAll()
                .antMatchers(serverPath + "/images/**").permitAll()
                .antMatchers(serverPath + "/webjars/**").permitAll()
                .antMatchers(serverPath + "/v2/api-docs").permitAll()
                .antMatchers(serverPath + "/configuration/ui").permitAll()
                .antMatchers(serverPath + "/configuration/security").permitAll()
  

• 添加注解（非必须）
  • swagger2常用注解

  • @Api()用于类；
    表示标识这个类是swagger的资源

• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体使用举例说明： 
@Api() 
用于类；表示标识这个类是swagger的资源 
tags–表示说明 
value–也是说明，可以使用tags替代 
但是tags如果有多个值，会生成多个list

• 注解实例

@RestController
@Api(value = "首页", tags = "首页")
public class IndexController extends BaseController {

    /**
     *  注册
     *
     * @param userEntity
     * @throws BusinessException
     */
    @PostMapping(value = "${jwt.jwt_route_register}")
    @ApiOperation(value = "用户注册")
    public UserEntity register(UserEntity userEntity) throws BusinessException {
        userEntity.setCreateDate(new Date());
        userEntity.setStatus(1);
        userEntity.setBindType(1);
        UserEntity entity = userService.save(userEntity);
        entity.setPassword("");
        entity.setBindType(null);
        entity.setStatus(null);
        return entity;
    }


    /**
     * 登录
     *
     * @param loginName
     * @param password
     * @return
     * @throws BusinessException
     */
    @PostMapping(value = "/${jwt.jwt_route_authentication_path}")
    public String login(@ApiParam(value = "登录名", required = true) String loginName,@ApiParam(value = "密码", required = true) String password) throws BusinessException {
        String token = userService.login(loginName, password);
        return token;
    }

}

---

• userEntity中是的注解

         @ApiModelProperty(value = "id")
         private Integer id;
         @ApiModelProperty(value = "登录名")
         private String loginName;

可能出现的问题

• 访问方法，返回403；考虑jwt口令验证问题
• 无法访问http://localhost:8080/swagger-ui.html页面，出现白页或者弹框。考虑是spring security的url路径配置问题。解决方法：需要把swagger2的相关的url添加到其中去。

总结

• 页面效果
  
  
  
  下面可以点“try it now”可以直接进行测试啦。虽然没有postman那么强大，但是对于前后端分离的项目的来说，使用还是比较方便的，而且很快速。
• java中还有不少好用的脚手架，swagger就是其中一个。后面我会继续更新的。