SpringBoot 集成 Swagger2

Swagger 简介

1.为什么要使用Swagger

Swagger 通过配置和注解，可以对接口生成对应的api文档，有利于我们开始对接口的维护，更方便我们了解其中的业务

2.Swagger简介

Swagger是一款Restful接口的文档在线自动生成和功能测试

Swagger是一个规范和完整的框架，用于生成，描述，调用和可视化Restful风格的Web服务，总体目标是使客户端和文件系统作为服务器，以同样的速度来更新文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

SpringBoot整合Swagger

1.项目结构

 2.Swagger依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.21</version>
</dependency>

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.21</version>
</dependency>

【注意】：报错Swagger java.lang.NumberFormatException: For input string: ""

就添加下面两个注解，没有则添加上面两个

3.Swagger配置类

package cn.zb.swagger.config;

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
//启用Swagger2相关功能
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启（true 开启 false隐藏 生产环境建议隐藏）
                //.enable(false)
                .select()
                //扫描路径，设置basePackage会将报下所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("cn.zb.swagger.controller"))
                //指定路径处理PathSelectors.any() 代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //设置文档标题（Api名称）
                .title("SpringBoot中使用Swagger2接口规范")
                //文档描述
                .description("接口说明")
                //服务条款url
                .termsOfServiceUrl("http://localhost:8080/")
                //版本号
                .version("1.0.1")
                .build();
    }
}

4.编写测试代码

package cn.zb.swagger.controller;

import cn.zb.swagger.entity.Employee;
import cn.zb.swagger.service.EmployeeService;
import cn.zb.swagger.service.impl.EmployeeServiceImpl;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/employee")
@Api(value = "测试接口",tags = "员工管理相关的接口")
public class EmployeeController {
    @Autowired
    private EmployeeService employeeService;

    @PostMapping("/save")
    //方法说明
    @ApiOperation(value = "添加员工",notes = "添加员工")
    //方法参数说明，name参数名，value参数说明，dataType参数类型，required 是否必传，defaultValue默认值
    @ApiImplicitParam(name = "employee",value = "新增的员工数据",required = true,dataType = "Employee")
    public String saveEmployee(@RequestBody Employee employee){
        employeeService.save(employee);
        return "保存成功";
    }

    @GetMapping("/select")
    //方法说明
    @ApiOperation(value = "根据条件查询员工",notes = "根据条件查询员工")
    //方法参数说明，name参数名，value参数说明，dataType参数类型，required 是否必传，defaultValue默认值
    //多个参数声明
    @ApiImplicitParams({
            @ApiImplicitParam(name = "empId",value = "员工Id",required = true,dataType = "long"),
            @ApiImplicitParam(name="salary",value = "员工工资",required = true,dataType = "double")})
    public String selectEmployee(@RequestParam("empId") Long empId,@RequestParam("salary") double salary){
        List<Employee> employees = employeeService.list(new QueryWrapper<Employee>().ge("emp_id", empId).le("salary", salary));
        employees.forEach(System.out::println);
        return "查询成功";
    }

}

5.Swagger页面访问

运行项目，输入http://localhost:8080/swagger-ui.html 访问Swagger页面，页面如下：

​

 ​

 6.SpringSecurity中配置

如果项目中集成了Spring Security,接口会被拦截，需要在Spring Security的配类中冲configure方法，对接口进行过滤

@Override
public void configure(WebSecurity web) throws Exception {
    web.ignoring()
            .antMatchers("/swagger-ui.html")
            .antMatchers("/v2/**")
            .antMatchers("/swagger-resources/**");
}

本博客只是用来记录，参考了其他博主的博客