springboot（二）_简单的RESTful接口以及整合swagger2

本系列所有源码可以在github获取

springboot+jpa创建简单的RESTful增删改查

RESTful 是一种风格，而不是标准，客户端与服务器之间只要路径匹配，就可以请求到。REST 是”表现层状态转化”，所谓资源，可以理解为服务器上的信息，因此每一个URI，代表一个资源，利用这样的思想设计接口，会更加简洁。想要了解更多详情可以参考What is REST

下面开始代码实例，首先在 pom 中添加依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
</dependency>

lombok 可以在编译期生成getter，setter代码，以及使用 builder建造者模式构建实体。这里根据个人喜好，也可以在idea里使用快捷键生成代码。

在 application.properties 里添加数据库连接信息

spring.datasource.url=jdbc:mysql://localhost:3306/proctice?verifyServerCertificate=false&useSSL=false&requireSSL=false
spring.datasource.username=root
spring.datasource.password=password
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.jpa.database=MYSQL
spring.jpa.show-sql=true
spring.jpa.hibernate.ddl-auto=update
#配置数据库引擎
spring.jpa.database-platform=org.hibernate.dialect.MySQL5InnoDBDialect

新建 UserController，添加基础增删改查的方法

/**
 * @author zhyee
 * @date 2018/7/10 上午11:02
 */
@RestController
@RequestMapping("/users")
public class UserController {

    private final UserService userService;

    @Autowired
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping
    public List<User> getUsers() {
        return userService.getUsers();
    }

    @DeleteMapping("/{id}")
    public void deleteById(@PathVariable(value = "id") long id) {
        userService.deleteById(id);
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable(value = "id") long id, @RequestBody User user) throws Exception {
        user.setId(id);
        return userService.updateUser(user);
    }

    @PostMapping
    public User create(@RequestBody User user) {
        return userService.create(user);
    }
}

与单体架构一样，需要服务层来实现业务逻辑，下面是Service 层代码，由于业务逻辑简单，没有使用接口层。

/**
 * @author zhyee
 * @date 2018/7/10 上午11:27
 */
@Service
public class UserService {

    private final UserRepositury userRepositury;

    @Autowired
    public UserService(UserRepositury userRepositury) {
        this.userRepositury = userRepositury;
    }

    public List<User> getUsers() {
        return userRepositury.findAll();
    }

    public void deleteById(long id) {
        userRepositury.delete(id);
    }

    public User updateUser(User user) throws Exception {
        User origin = userRepositury.findOne(user.getId());
        if (Objects.isNull(origin)) {
            throw new Exception("用户不存在");
        }
        if (!Objects.isNull(user.getPhoneNumber())) {
            origin.setPhoneNumber(user.getPhoneNumber());
        }
        if (!Objects.isNull(user.getUserName())) {
            origin.setUserName(user.getUserName());
        }
        if (!Objects.isNull(user.getEmail())) {
            origin.setEmail(user.getEmail());
        }
        return userRepositury.save(origin);
    }

    public User create(User user) {
        return userRepositury.save(user);
    }
}

新建 UserRepositury 接口继承 JpaRepository ，Repository 是 JPA 封装好的一系列数据访问的接口，基本的sql语句代码已经实现了，在这个demo中，我们只需要继承 JpaRepository 接口，就可以直接使用基本的增删改查

/**
 * @author zhyee
 * @date 2018/7/10 上午11:25
 */
@Repository
public interface UserRepositury extends JpaRepository<User,Long> {
}

到这里，代码就都完成啦，接下来，访问 http://localhost:8099/users (请求获取用户列表的方法)，会得到返回值 “[]” ，当前数据库还没有内容，可以使用postman调试其余接口。

也可以继续集成 swagger2 ，使用 swagger-ui 调试接口

集成 swagger2

在pom中添加 swagger2 的依赖

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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

编写一个 swagger的配置类

/**
 * @author zhyee
 * @date 2018/7/10 下午1:55
 */
@EnableSwagger2
@Configuration
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("top.zhyee.springbootproctice"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多Spring Boot相关文章可以参考：http://zhyee.top/")
                .termsOfServiceUrl("http://zhyee.top/")
                .version("1.0")
                .build();
    }
}

然后在我们之前的 UserController 中，添加对方法的注释，使用 @ApiOperation @ApiImplicitParam注解，修改后的Controller如下

/**
 * @author zhyee
 * @date 2018/7/10 上午11:02
 */
@RestController
@RequestMapping("/users")
public class UserController {

    private final UserService userService;

    @Autowired
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @ApiOperation(value = "获取用户列表")
    @GetMapping
    public List<User> getUsers() {
        return userService.getUsers();
    }

    @ApiOperation(value = "根据id删除用户")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")
    @DeleteMapping("/{id}")
    public void deleteById(@PathVariable(value = "id") long id) {
        userService.deleteById(id);
    }

    @ApiOperation(value = "根据id修改用户")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")
    @PutMapping("/{id}")
    public User updateUser(@PathVariable(value = "id") long id, @RequestBody User user) throws Exception {
        user.setId(id);
        return userService.updateUser(user);
    }

    @ApiOperation(value = "创建新用户")
    @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User")
    @PostMapping
    public User create(@RequestBody User user) {
        return userService.create(user);
    }
}

配置完成，启动项目，然后访问 http://localhost:8099/swagger-ui.html 就可以看到页面啦

每个方法里有详细的传参规范与参数返回示例，并且可以直接使用接口进行调试。