Spring Boot中使用Swagger2构建RESTful APIs

继续Spring Boot 的学习,这次我们加入Swagger2方便Web调试。下面我们就开始了。

在pom.xml文件中引入Swagger2.

<!--添加swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

然后我们需要在Application同级目录下添加Swagger2的配置类。

package com.seawater;

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

/**
 * Created by zhouhs on 2016/12/30.
 */
@Configuration
@EnableSwagger2
public class Swagger2Configure {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.seawater.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("Spring Boot Swagger2")
                .termsOfServiceUrl("http://blog.csdn.net/zhouseawater")
                .contact("seawater")
                .version("1.0")
                .build();
    }

}

@ Configuration注解告诉Spring加载这个类的配置。

@EnableSwagger2 启用Swagger2。

apiInfo()方法添加API的基本信息.

接下来新建一个User实体类。

package com.seawater.bean;

/**
 * Created by zhouhs on 2016/12/30.
 */
public class User {

    private String id;
    private String name;
    private int age;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    } 

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

UserController

package com.seawater.controller;

import com.seawater.bean.User;
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.*;

/**
 * Created by zhouhs on 2016/12/30.
 */
@RestController
@RequestMapping(value = "/user")
@Api(description = "用户")
public class UserController {

    static Map<String,User> userMap = Collections.synchronizedMap(new HashMap<String, User>());

    @ApiOperation(value = "获取用户列表")
    @RequestMapping(value = "/getUserList" , method = RequestMethod.GET)
    public List<User> getUserList(){
        List<User> userList = new ArrayList<User>(userMap.values());
        return userList;
    }


    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value="/addUser", method=RequestMethod.POST)
    public String addUser(@RequestBody User user) {
        userMap.put(user.getId(), user);
        return "success";
    }

    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String")
    @RequestMapping(value="/getById/{id}", method=RequestMethod.GET)
    public User getById(@PathVariable String id) {
        return userMap.get(id);
    }


    @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    @RequestMapping(value="/updateById/{id}", method=RequestMethod.PUT)
    public String updateById(@PathVariable String id, @RequestBody User user) {
        User u = userMap.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        userMap.put(id, u);
        return "success";
    }


    @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String")
    @RequestMapping(value="/deleteById/{id}", method=RequestMethod.DELETE)
    public String deleteById(@PathVariable String id) {
        userMap.remove(id);
        return "success";
    }

}

主要就是定义CRUD操作。

完成后我们启动项目，访问http://localhost:8081/swagger-ui.html(端口号不同的要访问自己的配置的端口，我这里配置的是8081)

结果如图：

点开user-controller就可以看到我们定义的方法了。

点开方法，会得到更加具体的信息。

测试就按照参数输入就可以进行测试了。

到这里我们添加Swagger就结束了。

源码地址(项目中的源码可能会更多哦，需要自己找到对应源码)