Springboot 学习之Swagger2整合

背景 在如今前后端分离的大背景下，前后端唯一打交道的就是API接口。前端只需要向后端请求url地址，后端只需将数据返回即可。前端工程师拿到的既是后端给到的一份完整的API文档，如果项目体量非常大的情况下，整理这些文档就需要浪费大量的时间。如果业务有变更的情况下，还需要再去更新文档，维护成本也是非常大。

今天介绍的主角就是Swagger在线生成API文档，极大的减少了人力的维护成本。可以在线直接在文档接口中测试。主要演示一下与Springboot整合的使用。Swagger支持多种语言的整合，详细可以通过查看其它资料。也支持文档的编写, 文档编写。

整合步骤

引入依赖文件

<!--swagger2-->
       <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>

编写配置文件

package cc.mrbird.common.swagger;

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;

/**
 * @Auther: jerry.feng
 * @Date: 2018/11/5
 * @Description: Swagger2 配置
 */

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //api文档扫描的包
                .apis(RequestHandlerSelectors.basePackage("cc.mrbird.system.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("CloudWallet API文档")
                .description("CloudWallet 云钱包 RESTful接口文档")
                .termsOfServiceUrl("https://blog.youkuaiyun.com/fw19940314/article/list/")
                .version("1.0.1")
                .build();
    }
}

开启Swagger 通过@EnableSwagger2 注解

@SpringBootApplication
@EnableTransactionManagement
@EnableCaching
@EnableSwagger2
@EnableAsync
public class Application {
    private static Logger log = LoggerFactory.getLogger(Application.class);
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
        log.info("FEBS started up successfully at {} {}", LocalDate.now(), LocalTime.now());
    }
}

API（Controller）层的编写只截取了部分，一个是带参数，一个是无参数

@RestController
public class DeptController {
    private Logger log = LoggerFactory.getLogger(this.getClass());
    @Autowired
    private DeptService deptService;

    @ApiOperation(value="获取部门信息", notes="获取所有部门信息")
    @RequestMapping(value = "dept/tree", method = RequestMethod.GET)
    @ResponseBody
    public ResponseBo getDeptTree() {
        try {
            Tree<Dept> tree = this.deptService.getDeptTree();
            return ResponseBo.ok(tree);
        } catch (Exception e) {
            log.error("获取部门树失败", e);
            return ResponseBo.error("获取部门树失败！");
        }
    }
    @ApiOperation(value="查询部门信息", notes="根据url的id来获取部门详细信息")
    @ApiImplicitParam(name = "deptId", value = "部门ID", required = true, dataType = "Long")
    @RequestMapping(value = "dept/getDept", method = RequestMethod.GET)
    @ResponseBody
    public ResponseBo getDept(Long deptId) {
        try {
            Dept dept = this.deptService.findById(deptId);
            return ResponseBo.ok(dept);
        } catch (Exception e) {
            log.error("获取部门信息失败", e);
            return ResponseBo.error("获取部门信息失败，请联系网站管理员！");
        }
    }
}

注解的使用：
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

启动项目，访问http://localhost:8080/swagger-ui.html#/

这里是使用在真实的项目中，接口有很多，刚才创建的RESTful风格的dept-controller。

在线测试，即可获取接口数据。

这里需要说一点的是可能项目中使用了权限框架，会拦截Swagger请求的资源，例如我这里使用的shiro安全框架。需要讲Swagger这部分资源设置为免登陆认证。

//在shiroFilterFactoryBean，filterChainDefinitionMap过滤器中放行这几个请求即可。
        filterChainDefinitionMap.put("/swagger-ui.html", "anon");
        filterChainDefinitionMap.put("/webjars/**", "anon");
        filterChainDefinitionMap.put("/v2/**", "anon");
        filterChainDefinitionMap.put("/swagger-resources/**", "anon");

到这里基本的开发API文档就生成成功

参考文章：https://blog.youkuaiyun.com/saytime/article/details/74937664