Springboot2集成Swagger2

swagger

它是一个功能强大的api框架，它的集成非常简单，不仅提供了在线文档的查阅，而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api。

---

Swagger概述

Swagger是一组围绕OpenAPI规范构建的开源工具，可帮助设计、构建、记录和使用REST API。简单说下，它的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要认为的维护这个接口进行测试。

---

Swagger常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiParamImplicitL：一个请求参数
@ApiParamsImplicit 多个请求参数

---

集成Swagger

加入依赖：

截止2018.7.19最新版本。

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

添加SwaggerConfiguration配置

与启动类同级包建立Swagger2

Swagger2.java

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {
    //swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("cookie", "http://www.baidu.com", "[email protected]"))
                //版本号
                .version("1.0")
                //描述
                .description("用户管理")
                .build();
    }

}

通过@Configuration注解，表明它是一个配置类，@EnableSwagger2开启swagger2。

apiINfo()配置一些基本的信息。apis()指定扫描的包会生成文档。再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。

select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

---

Controller文档内容

一下以用户为例：

import com.example.demo.model.User;
import com.example.demo.service.UserService;
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;
@Api(value = "usercontroller",description = "用户管理")
@RestController
public class UserController {
    @Autowired
    private UserService userService;

    /**
     * 获取用户列表
     * @return list
     */
    @ApiOperation(value ="查询所有用户",notes ="",httpMethod = "GET")
    @GetMapping("/user")
    public List<User> userList(){
     return  userService.selectAllUser();
    }

    /**
     * 查询用户根据id
     * @return USer对象
     * @param  id
     */
    @ApiOperation(value = "查询用户",notes = "根据用户id查询用户",httpMethod = "GET")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String")
    @GetMapping("/user/{id}")
    public User getUserById(@PathVariable String id){
        User user  = userService.selectByPrimaryKey(id);
        return user;
    }

    /**
     * 新增User
     * @param user
     * @return success or error
     */
    @ApiOperation(value = "新增用户",notes = "",httpMethod = "POST")
    @ApiImplicitParam(name = "user",value = "用户实体",required = true,dataType = "User")
    @PostMapping("/user")
    public String createUser(@RequestBody User user){
       int num =  userService.insert(user);
       if(num>0){
           return "success";
       }
        return "error";
    }

    /**
     * 更新User
     * @param user
     * @return success or error
     */
    @ApiOperation(value = "更新用户",notes = "根据用户id更新用户",httpMethod = "PUT")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String"),
            @ApiImplicitParam(name = "user",value = "用户实体,传入更改后的数据",required = true,dataType = "User")
    })
    @PutMapping("user/{id}")
    public String updateUser(@PathVariable String id,@RequestBody User user){
       int num =  userService.updateByPrimaryKey(user);
        if(num>0){
            return "success";
        }
        return "error";
    }

    /**
     * 删除用户
     * @param id
     * @return success or error
     */
    @ApiOperation(value = "删除用户",notes = "",httpMethod = "DELETE")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String")
   @DeleteMapping("user/{id}")
    public String deleteUser(@PathVariable String id){
        int num = userService.deleteByPrimaryKey(id);
       if(num>0){
           return "success";
       }
        return "error";
    }

}

最后启动项目：访问 http://localhost:8080/swagger-ui.html