springboot整合swagger

springboot整合swagger

对于开发来说编写接口文档是痛苦的，且文档有知识传承的作用，对新来的员工及后续的维护很友好，所以swagger就诞生了；它可以为我们自动建立接口文档，我们只需要在我们的项目中调用简单的“注解”即可。

1、新建springboot项目：
新建项目就不过多描述了，直接进入主题

2、导入swagger依赖，整合swagger：
在pom.xml中：

<!--整合swagger：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>

3、导入依赖后，需要配置swagger：
在项目中新建一个配置类，建议新建一个包，用来存储配置类的：
SwaggerConfig.class:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置swagger
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
        		//配置该api文档的基本信息
                .apiInfo(apiInfo())
                //enable：是否需要开启swagger功能 (默认开启，true 开启，false隐藏)
                //.enable(false)
                .select()
                //配置需要扫描的路径（包）,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.springboot.mybatis.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }
    //该api文档信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            //设置文档标题(API名称)
            .title("SpringBoot中使用Swagger2接口规范")
            //文档描述
            .description("接口说明")
            //服务条款URL
            .termsOfServiceUrl("http://localhost:8080/")
            //版本号
            .version("1.0.0")
            .build();
    }
}

4、在配置类中使用swagger注解：从而自动生成接口文档
创建一个controller类：MyController.class
使用 @RestController 和 @Api 标注

常用的注解：

注解	介绍
@ApiImplicitParam	对单个参数的说明；注解的参数：name参数名；value参数说明，备注；dataType参数类型；required 是否必传；defaultValue 默认值
@ApiImplicitParams	作用在方法上，用在请求的方法上，包含一组参数说明
@ApiOperation	作用在方法上，对方法（api）进行说明
@ApiModel	作用在类上，一般在使用对象来接收参数时，我们没有办法使用@ApiImplicitParam来标注参数信息，如： public ResponseMsg login(@RequestBody Account a){}，我们需要在这个ResponseMsg这个类上使用@ApiModel标注，一般在bean类上标注，注解的参数：description：描述
@ApiModelProperty	标注在使用@ApiModel标注的类中的属性

@ApiModel和@ApiModelProperty的使用：

//bean类：
@ApiModel(description = "返回信息")
public class ResponseMsg {
    @ApiModelProperty(value = "返回的数据")
    private Object Data;
    @ApiModelProperty(value = "返回的信息")
    private String msg;
    @ApiModelProperty(value = "返回的状态")
    private Integer status;
}

得到：

@ApiImplicitParams的使用：

@ApiImplicitParams({
    @ApiImplicitParam(name = "username",value = "用户名"),
    @ApiImplicitParam(name = "password",value = "密码")
})
public String insert(@RequestParam("username") String Username,@RequestParam("password") String Password){
    return "插入成功";
}

完整的代码

@RestController
@Api(value = "测试接口", tags = "用户管理相关的接口", description = "用户测试接口")
public class MyController {
    @Autowired
    UserService userService;

    @Autowired
    AccountService accountService;

    @GetMapping("/get_data")
    //方法参数说明
    @ApiImplicitParam(name = "id", value = "用户id",dataType = "Integer",required = true)
    //说明是什么方法(可以理解为方法注释)
    @ApiOperation(value = "根据id获取数据", notes = "根据id获取数据")
    public User getData(@RequestParam("id") Integer id){
        return userService.getDataById(id);
    }
    
	@GetMapping("/insert")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",value = "用户名"),
            @ApiImplicitParam(name = "password",value = "密码")
    })
    public String insert(@RequestParam("username") String Username,@RequestParam("password") String Password){
        return "插入成功";
    }

    @ApiOperation(value = "登录", notes = "登录")
    @PostMapping("/login")
    public ResponseMsg login(@RequestBody Account a, HttpServletRequest req){
        ResponseMsg rm = new ResponseMsg();
        String msg = "登录成功";
        int code = 200;
        Account account = accountService.login(a.getUsername(),a.getPassword());
        if(account != null){
            msg = "登录成功";
            code = 200;
            HttpSession session = req.getSession();
            session.setAttribute("username",account.getUsername());
            session.setAttribute("password",account.getPassword());
            session.setAttribute("userId",account.getId());
        }else{
            code = 500;
            msg = "登录失败";
        }
        rm.setMsg(msg);
        rm.setStatus(code);
        rm.setData("登录成功");
        return rm;
    }

}

5、访问swagger生成的接口文档：
url: http://localhost:8080/swagger-ui.html

6、注意：
1、如果项目配置了拦截器：一定要在拦截器中取消拦截swagger页面，否则无法访问接口文档
配置如下：

//配置拦截器
@Configuration
public class AdminWebConfig implements WebMvcConfigurer {
    //添加拦截
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new LoginInterceptor())
                .addPathPatterns("/**")  //配置需要拦截的请求，/** 拦截所有，包括静态资源
                .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/swagger-ui.html/**","/","/login","/css/**","/fonts/**","/images/**","/js/**");  //配置无须拦截的请求
    }
}

主要是如下代码：

.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/swagger-ui.html/**","/","/login","/css/**","/fonts/**","/images/**","/js/**");  //配置无须拦截的请求

2、@ApiImplicitParam 中的dataType参数，必须与函数中对应的参数类型一致，如：