springboot整合swagger2，前后端对接so easy

前后端分离项目中，各自按照接口文档进行开发，然后对接，项目上线。当然这是理想状态，开发过程中肯定会遇到接口内容变化的情况，这时候如果有工具能够实时监控变化，并且易于查看，无疑减轻了大量工作，那么swagger2绝对是必备技能。下面搭建一个demo看一下有多方便！

1，创建springboot工程，引入相关依赖

       <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency> 
        <!-- web工程依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger2必须依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger2界面展示依赖 -->

2，swagger2相关配置

@Configuration
@EnableSwagger2
public class swagger2config {
    @Bean
    Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.light.swagger2.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder().description("前后端接口文档信息")
                        .title("测试项目接口信息")
                        .version("V1.0")
                        .license("Apache2.0")
                        .build());
    }
}

新建configuration配置类，对swagger2进行相应配置，当然可以添加其余自己需要的配置

3，创建测试所需bean

@ApiModel(value = "用户实体类",description = "用户实体类描述")
public class User {
    @ApiModelProperty(value = "用户id")
    private Integer id;
    @ApiModelProperty(value = "用户名")
    private String name;
    @ApiModelProperty(value = "地址")
    private String address;
    ---------------省略get、set方法
    }

如果参数比较复杂，也可以在实体类中进行描述

4，创建接口

@RestController
@Api(tags = "用户接口数据")
public class UserController {
    @ApiOperation(value = "查询用户",notes = "根据用户id查询用户")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "99")
    @GetMapping("/user")
    public User getUserById(Integer id){
        User user=new User();
        user.setId(id);
        user.setName("Light");
        user.setAddress("浙江省杭州市");
        return user;
    }
    @ApiOperation(value ="删除用户",notes = "根据id删除用户")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "99")
    @ApiResponses({
            @ApiResponse(code = 200,message = "删除成功"),
            @ApiResponse(code = 500,message = "删除失败")
    })
    @DeleteMapping("/user/{id}")
    public void deleteUserById(@PathVariable Integer id){
        System.out.println("deleteUserById"+id);
    }
    @ApiOperation(value ="更新用户",notes = "根据用户id更新用户名")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",value = "用户名",required = true,defaultValue = "Light"),
            @ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "99")
    })
    //@ApiIgnore  接口未完成时可以不再swagger中显示
    @PutMapping("/user")
    public User updateUserById(String username,Integer id){
        User user = new User();
        user.setId(id);
        user.setName(username);
        return user;
    }
    @ApiOperation(value = "添加用户",notes = "添加用户信息")
    @PostMapping("/user")
    public User addUser(@RequestBody User user){
        return user;
    }
}

相关接口描述
4.1，@Api注解用来标记当前Controller的功能。
4.2，@ApiOperation注解方法的作用。
4.3，@ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值。如果有多个参数，需要使用多个@ApiImplicitParam注解来描述，多个 @ApiImplicitParam注解必须放在一个@ApiImplicitParams注解中。需要注意的是@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2内必填，没有Swagger2，这个限制就没用了，如果开发者需要指定一个参数必填，还是需要使用@RequestParam(required = true)注解。
4.4，如果参数是一个对象（代码片中的添加接口），对于参数的描述也可以放在实体类中，如目录3中描述
4.5，@ApiIgnore 接口未完成时，使用此注解可以不再swagger2-UI中展示

5，swagger2界面展示

5.1 项目启动后，浏览器访问 http://localhost:8080/swagger-ui.html 则可以看到相关接口信息，如下图：

5.2 models中可以看到之前实体类中的描述

5.3 接口信息也都会显示，包括请求方式、地址、名称

5.4 点开一个也可以进行测试

额外补充知识点，spring security中如何配置swagger2

如果Spring Boot项目中集成了Spring Security，不做额外配置的话，Swagger2文档可能会被拦截，此时需要在Spring Security的配置类中重写configure方法，添加过滤：

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

知识有限，如有错误望理解。另外推荐一个大神个人博客，讲的内容很多很全面。 江南一点雨