Spring boot构建RESTFul API+使用Swagger2构建API文档

RESTFUL API设计

请求类型	资源地址	操作说明
GET	/V0.1/customers/	获取所有客户
POST	/V0.1/customers/	新建一个客户
GET	/V0.1/customers/{id}	根据id查询客户
PUT	/V0.1/customers/{id}	根据id更新客户信息
DELETE	/V0.1/customers/{id}	根据id删除客户信息

操作接口（返回值并未安装标准RESTFul API设计编写）

@RestController
@RequestMapping(value = "/V0.1/customers")
public class CustomerCtroller {

    static Map customers =  Maps.newHashMap();

    @ApiOperation(value = "获取用户列表", notes = "")
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public List getCustomerList() {
        List result = new ArrayList(customers.values());
        return result;
    }

    @ApiOperation(value = "创建用户", notes="根据customer对象创建用户")
    @RequestMapping(value = "/", method = RequestMethod.POST)
    public String postCustomer(@ModelAttribute Customer customer) {
        customers.put(customer.getId(), customer);
        return "success";
    }

    @ApiOperation(value = "获取用户详细信息", notes="根据id获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", paramType="path", dataType="long")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    public Customer getCustomer(@PathVariable Long id) {
        return customers.get(id);
    }

    @ApiOperation(value = "更新用户详细信息", notes="根据id更新用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", paramType="path", dataType="long")
    @RequestMapping(value = "/{id}", method = RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @ModelAttribute Customer customer) {
        Customer cus = customers.get(id);
        cus.setName(customer.getName());
        cus.setAge(customer.getAge());
        return "success";
    }

    @ApiOperation(value = "删除用户信息", notes="根据id删除用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", paramType="path", dataType="long")
    @RequestMapping(value = "{id}", method = RequestMethod.DELETE)
    public String deleteCustomer(@PathVariable Long id) {
        customers.remove(id);
        return "success";
    }
}

测试用例可参考上一篇博文。

Swagger2构建API文档

上一节代码中的@ApiOperation注解用于API方法说明，@ApiImplicitParam用于参数说明。这么一看swagger2侵入性很强，严重污染代码！

在build.gradle中加入依赖：

"io.springfox:springfox-swagger2:${Swagger2Version}",
"io.springfox:springfox-swagger-ui:${SwaggerUiVersion}"

版本配置在父buil.gradle中，可以自行去maven仓库中搜索。

swagger2配置类

@Configuration
@EnableSwagger2
public class Swagger2 {

    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
           .apis(RequestHandlerSelectors.basePackage("com.siva.customer.web"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Customer RESTful APIs")
                .description("我的博客：http://blog.csdn.net/sivannnn")
                .termsOfServiceUrl("http://blog.csdn.net/sivannnn")
                .version("0.1")
                .build();
    }
}

为何不使用xml配置？因为spring4零配置文件，就是这么任性。
搞定之后，访问：http://localhost:8080/swagger-ui.html#/看下效果

根据代码中编写的注解，会生成相应的说明，并提供API调试功能

参考：
1.http://swagger.io/
2.http://www.ruanyifeng.com/blog/2014/05/restful_api.html