Spring Boot构建RESTful API

项目需求:搭建前后台项目分离项目,提供良好的接口文档,避免了写开发对接文档的时间.

操作步骤:

1. 添加在pom.xml中添加依赖
2. 编写SwaggerConfig配置文件信息
3. 编写实体类
   1. @ApiModel(value = "Employee", description = "员工信息") 实体类描述信息
   2. @ApiModelProperty(value = "员工编号") 为字段添加说明
4. 编写controller类
   1. @Api(value = "/employee", description = "员工管理") 请求路径说明
   2. @RestController：Spring4之后加入的注解，原来在@Controller中返回json需要@ResponseBody来配合，默认返回Json格式
   3. @RequestMapping：配置url映射
   4. @ApiOperation(value = "获得员工列表") 修饰方法,为方法添加说明
   5. @RequestMapping(value="/list", method= {RequestMethod.GET,RequestMethod.POST}) 请求路径,并确定请求方式Post还是Get

   6. @ApiImplicitParams({
              @ApiImplicitParam(paramType = "query", name = "id", value = "员工标号", required = true, dataType = "double")})   修饰方法,为请求参数做说明,required是否能为空,dataType为请求参数类型 

操作如下:

Pom.xml文件中添加依赖:

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

SwaggerConfig配置文件编写:

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        List<ResponseMessage> responseMessageList = new ArrayList<>();
        responseMessageList.add(new ResponseMessageBuilder().code(200).message("响应成功").build());
        responseMessageList.add(new ResponseMessageBuilder().code(400).message("错误的请求").build());
        responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到资源").build());
        responseMessageList.add(new ResponseMessageBuilder().code(500).message("服务器内部错误").build());
        responseMessageList.add(new ResponseMessageBuilder().code(503).message("服务器暂时不可用").build());

        return new Docket(DocumentationType.SWAGGER_2)
                .globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot的学习之路") // 标题
                .description("接口文档") // 描述
                .contact(new Contact("老乡", "", "123456@qq.com")) // 联系方式
                .version("1.0") // 版本号
                .build();
    }
}

 

Employee员工实体类:

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "Employee", description = "员工信息")
public class Employee {

    @ApiModelProperty(value = "员工编号")
    private int id;
    @ApiModelProperty(value = "员工姓名")
    private String name;
    @ApiModelProperty(value = "员工年龄")
    private int age;
    @ApiModelProperty(value = "创建时间")
    private String createTime;
    @ApiModelProperty(value = "是否禁用")
    private boolean state;

    // 省略get和set
}

Controller层实现:

import com.example.advanced.entity.Employee;
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.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@Api(value = "/employee", description = "员工管理")
@RestController
@RequestMapping(value="/employee")
public class EmployeeController {

    @Autowired
    EmployeeService employeeService;

    @ApiOperation(value = "获得员工列表")
    @RequestMapping(value="/list", method= {RequestMethod.GET,RequestMethod.POST})
    public List<Employee> list(Employee employee) {
        return employeeService.list(employee);
    }

    @ApiOperation(value = "新增员工")
    @RequestMapping(value="/add", method= RequestMethod.POST)
    public Employee add(Employee employee) {
        return employeeService.add(employee);
    }

    @ApiOperation(value = "根据Id删除员工")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "id", value = "员工标号", required = true, dataType = "double")
    })
    @RequestMapping(value="/delete", method= RequestMethod.DELETE)
    public Employee add(int id) {
        return employeeService.delete(id);
    }


}

打开接口页面: http://localhost:8080/swagger-ui.html#/

最终效果:

打开列表

总结:可以看出字段说明,请求路径,请求参数都一目了然