SpringBoot使用Swagger2构建API文档

　　后端开发中经常需要对移动客户端提供RESTful API接口，在后期版本快速迭代的过程中，修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致写出的代码与接口文档不一致现象。

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

　　

 1.在pom.xml中加入swagger2依赖

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

2.创建swagger2配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
     @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.offcn.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2构建RESTful APIs")
                    .description("描述描述")
                    .termsOfServiceUrl("http://www.baidu.com/")
                    .contact("Sunny")
                    .version("1.0")
                    .build();
        }
}

3.Controller增加文档注释

通过@ApiImplicitParams@ApiImplicitParam注解来给参数增加说明

@RestController
@EnableConfigurationProperties({User.class})
@RequestMapping("/user")
public class UserController {

    @Autowired
    User user;

    private List<User> listUser= Collections.synchronizedList(new ArrayList<User>());

    //查询所有
    @GetMapping("/")
    @ApiOperation(value="查询All用户信息", notes="All用户信息")
    public List<User> getAllUser(){
        return listUser;
    }
    //获取指定id的user
    @GetMapping("/{id}")
    @ApiOperation(value="查询指定id用户信息", notes="根据id查用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    public User getUser(@PathVariable("id") Long id){
        for(User u:listUser){
            if(u.getId()==id){
                return user;
            }
        }
        return null;
    }
    //插入
    @PostMapping("/")
    @ApiOperation(value="插入用户", notes="插入用户信息")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    public String insert(User user){
        listUser.add(user);
        return "success";
    }
    //根据id修改
    @PutMapping("/{id}")
    @ApiOperation(value="更新指定id用户信息", notes="根据id更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    public String update(@PathVariable("id") Long id,User user){
        for (User user2 : listUser) {
            if(user2.getId()==id) {
                user2.setName(user.getName());
                user2.setAge(user.getAge());
            }
        }
        return "success";
    }
    //根据id删除
    @DeleteMapping("/{id}")
    @ApiOperation(value="删除指定id用户信息", notes="根据id删除用户信息")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")
    public String delete(@PathVariable("id") Long id){
        listUser.remove(getUser(id));
        return "success";
    }

}

4.启动tomcat：

访问地址：http://localhost:8080/swagger-ui.html

即可看到上面的API