基于SpringBoot和Swagger2开发RESTful风格的javaweb项目

什么是RESTful风格？

第一次听到Restful这个词，总会想到它的中文翻译：平静的。当然这里的restful当然不是指这个词，而是REpresentational State Transfer的缩写。在web开发中，有五个常见的method：Get、Post、Put、Patch、Delete，不同的Method是对同一件事情做不同的操作：

Get：取得数据或状态；

Post：新增一项数据；

Put：更新数据；

Patch：更新数据；

Delete：删除数据

REST指的是网络中Client端和Server端的一种呼叫服务形式，通过既定的规则，满足约束条件和原则的应用程序设计就是Restful风格的设计，对资源的操作包括获取、创建、修改和删除资源，这些操作就是依照我们前面所提到的HTTP Method: GET、POST、PUT、PATCH和DELETE。这正好会对应到资料库基本操作CRUD

比如，当使用非REST风格进行增删改查时，会这样操作：

获得商品资料：GET /getAllItems

获得商品资料：GET /getItem/11

新增商品资料：POST /createItem

更新商品资料：POST /updateItem/

删除商品资料：POST /deleteItem/

而当使用RESTful API进行开发时，就变成下面这样：

获取商品资料：/GET /items

获取商品资料：/GET /items/1

新增商品资料：/POST /items

更新商品资料：/PATCH /items/1 

删除商品资料：/DELETE /items/1

RESTful风格的出现是为了给前后端提供更加简洁的API接口，而如何创建一份简单高效的API接口也并非一件简单的事情，尤其是当接口众多的时候，就会让接口创建变得十分吃力，Swagger2应运而生，Swagger2既可以减少创建API文档的工作量，同时说明内容又可以整合到代码之中去，让维护文档和修改代码整合为一体，Swagger2还提供了页面测试功能来调试每一个接口。

基于SpringBoot和Swagger2开发RESTful风格的api接口文档

1.创建Springboot项目：

本次实践依旧使用idea，github源码文末自取。首先创建一个SpringBoot项目，在pom.xml中添加相关依赖，主要Swagger2依赖为下面两个：

<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>

2.创建User实体类

因为项目比较简单，实现User类的增删改查API接口，因此全部放在一个文件夹之下，创建User.java

package com.sdxb.restfultest;

public class User {
    private Long id;
    private String name;
    private Integer age;
    //此处省略setter and getter
}

3.创建Swagger2配置文件

Swagger2的配置文件比较简单，添加一些固定的参数：

@Configuration
@EnableSwagger2
public class Swagger2{
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
        //创建api基本信息
                .apiInfo(apiInfo())
                .select()
        //指定扫描的包路径，Swagger会扫描包下所有Controller定义的API        
                .apis(RequestHandlerSelectors.basePackage("com.sdxb.restfultest"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("RestFul Test")
                .description("实现User类的增删改查")
                .termsOfServiceUrl("NO terms of service")
                .contact(new Contact("少掉下巴","https://blog.csdn.net/qq_41973594","[email protected]"))
                .version("1.0")
                .build();
    }
}

其中@Configuration注解使得Spring启动该配置类，@EnableSwagger2启动Swagger2

4.创建Controller，定义API

package com.sdxb.restfultest;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.*;

@Api(value = "用户信息管理")
@RestController
@RequestMapping(value="/users")
public class UserController {

    //创建一个线程安全的map
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    //获取User列表
    @ApiOperation(value="获取用户列表", notes="")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List<User> getUserList() {
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }
    //根据用户id删除用户
    @ApiOperation(value = "删除用户",notes = "根据id删除用户")
    @ApiImplicitParam(name = "id",value = "输入用户id",required = true,dataType = "Long")
    @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
    public String DeleteList(@PathVariable Long id){
        users.remove(id);
        return "success";
    }
    //创建用户
    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value="", method=RequestMethod.POST)
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }
    //根据用户id获取用户信息
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @RequestMapping(value="/{id}", method=RequestMethod.GET)
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }
    //根据指定id更新对象
    @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    @RequestMapping(value="/{id}", method=RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }
}

以上代码乍一看有很多的配置文件，其实实际使用起来很简单，通过@Api、@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。注解各个参数的功能如下：

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
        
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性        

5.运行项目

完成全部代码之后，启动SpringBoot项目，在浏览器上输入http://localhost:8080/swagger-ui.html，就能看到RESTful API接口界面

Swagger的接口测试也很简单，接下来测试一下用户创建

点击try it out，出现输入框，在controller中我们设置的输入类型是User，因此需要输入id，name和age：

点击下方的Execute，可以看到返回结果和状态，基本测试方法就是如此，至此，基于SpringBoot和Swagger2开发RESTful风格的api接口文档就创建完成，附上github地址：

github地址