Spring Boot 使用swagger2

swagger2可以减少我们的编写文档工作，尤其现在是前后端分离。后端写好接口之后还需要写API使用文档给客户端人员，尤其是在接口变更之后，文档往往就得不到及时的更新甚至是遗忘，导致文档最终变得不可信。这个框架可以帮助解决此类问题，减少后端人员的工作量，同时还能保持维护文档的地方只有一处。

这个框架也只是帮助减少上述问题，如果只是修改了代码，而没有更新相应的描述信息等，也是会存在上述问题的。

一、准备工作

添加依赖，在pom.xml文件添加如下的依赖：

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

二、配置swagger2

在Application.java平级的包下，新建一个Swagger2的类，内容如下，其中需要注意的是createRestApi方法下的包名为自己项目中的包名，一般为控制器所在的包。

**
 * Swagger2配置类
 * 1）在集成spring boot时，放在与Application.java同级目录下
 * 2）@Configuration注解的作用是让spring 来加载该类的配置
 * 3）@EnableSwagger2 是用来启用swagger2
 *
 * @author xiaozhao
 * @date 2018/10/19下午3:14
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    /**
     * 指定扫描包的路径来指定要创建API的目录，一般是控制器这个包
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xiaozhao.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 设置API的基本信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("我的公司")
                .description("后端接口说明文档")
                .termsOfServiceUrl("https://www.jianshu.com")
                .version("1.0")
                .build();
    }
}

image.png

三、swagger2常用注解说明

@Api()
value：不能显示到UI上
tags：一个字符串数组，说明整个类的作用，会显示在UI上。此处发现一个问题，就是为中文时，导致接口在UI上不能展开。

修饰在类上，描述一个类的作用。例如：

@Api(value = "欢迎", tags = {"用户操作接口说明"})
public class HelloController {
}

@ApiOperation()
value：说明方法的用途、作用
notes：方法的备注说明
修饰方法，说明方法的作用，例如：

    @GetMapping("/hi")
    @ApiOperation(value = "问候语", notes = "这是一个问候", httpMethod = "GET")
    public String hello() {
        return "Hell World";
    }

@ApiImplicitParams
是一个@ApiImplicitParam的数组，用在请求的方法上，包含一组参数说明
@ApiImplicitParam
name：参数名
value：参数的汉字说明，描述信息
required：是否必需
dataType：参数类型，默认String，其它值dataType="Integer" 或dataType="User" 或 ......
defaultValue：参数的默认值
paramType：参数放在哪个地方

            header --> 请求参数的获取：@RequestHeader
            query --> 请求参数的获取：@RequestParam
            path（用于restful接口）--> 请求参数的获取：@PathVariable
            body（不常用）
            form（不常用）

用来说明方法的参数，例如：

    @RequestMapping(value = "/update/{id}", method = RequestMethod.PUT)
    @ApiOperation(value = "更新信息", notes = "根据url的id来指定更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User")
    })
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        System.out.println(id);
        System.out.println(user.getId());
        System.out.println(user.getName());
        return "修改成功";
    }

@ApiParam
name：参数名
value：参数的汉字说明，描述信息
required：是否必需
用于方法、参数的说明，例如：

    @ApiOperation("更改用户信息")
    @PostMapping("/updateUserInfo")
    public int test(@RequestBody @ApiParam(name = "用户对象", value = "传入json格式", required = true) User user) {
        return 1;
    }

@ApiResponses
是一个@ApiResponse的数组，用于请求的方法上，表示一组响应
@ApiResponse()
code：标准的http响应码，例如404，500，502等
message：错误信息，例如“参数错误”
response：抛出异常的类
修饰方法，表达一个错误的响应，例如：

    @GetMapping("/hi")
    @ApiOperation(value = "问候语", notes = "这是一个问候", httpMethod = "GET")
    @ApiResponses({
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    public String hello() {
        return "Hell World";
    }

@ApiModel()
value：类名
description：描述

一般用于参数为一个实体类时，说明这个类的各项属性的含义。只能修饰在类上，需要配合@ApiProperty一起使用，例如：

@ApiModel
public class User implements Serializable {
    private static final long serialVersionUID = -1084928517040754103L;
}

@ApiModelProperty()
name：属性名称
value：描述
dataType：属性的数据类型
required：是否必填
example：举例说明
hidden：在文档上是否不可见

修饰实体类的属性，例如：

    @ApiModelProperty(value = "用户id", name = "id", required = false)
    private Integer id;

    @ApiModelProperty(value = "用户名称", name = "name", required = true,example = "张飒")
    private String name;


   //省略  getter and setter

image.png

*@ApiIgnore
可以修饰类或者非法，然后在文档中不再显示

四、项目中使用

用户实体类

/**
 * 用户实体类
 *
 * @author xiaozhao
 * @date 2018/10/19下午3:35
 */
@ApiModel
public class User implements Serializable {

    private static final long serialVersionUID = -1084928517040754103L;
    @ApiModelProperty(value = "用户id", name = "id", required = false)
    private Integer id;

    @ApiModelProperty(value = "用户名称", name = "name", required = true, example = "张飒")
    private String name;

    public Integer getId() {
        return id;
    }

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

    public String getName() {
        return name;
    }

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

    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", name='" + name + '\'' +
                '}';
    }
}

控制器

/**
 * swagger2 示例
 *
 * @author xiaozhao
 * @date 2018/10/19下午3:17
 */
@RestController
@RequestMapping("/api")
@Api(value = "Welcome", tags = {"User Guide"})
public class HelloController {

    /**
     * 无参数，只有说明
     *
     * @return 返回字符串
     */
    @GetMapping("/hi")
    @ApiOperation(value = "问候语", notes = "这是一个问候", httpMethod = "GET")
    @ApiResponses({
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    public String hello() {
        return "Hell World";
    }

    /**
     * 无参数
     *
     * @return 返回一个对象
     */
    @GetMapping("/list")
    @ApiOperation(value = "列表", notes = "获取用户列表", httpMethod = "GET")
    public HttpResult list() {
        HttpResult httpResult = new HttpResult();
        httpResult.setCode(0);
        httpResult.setMsg("");
        List<User> list = new ArrayList<>();
        User user = new User();
        user.setId(1);
        user.setName("James");
        list.add(user);
        httpResult.setData(list);
        return httpResult;
    }


    /**
     * 有一个简单类型的参数，rest风格
     *
     * @param id
     * @return
     */
    @RequestMapping(value = "/find/{id}", method = RequestMethod.GET)
    @ApiOperation(value = "查找用户", notes = "查找某个用户的详细信息")
    @ApiImplicitParam(name = "id", value = "用户唯一标识", required = true, dataType = "Long", paramType = "path")
    public User getBook(@PathVariable Long id) {
        System.out.println(id);
        User user = new User();
        user.setId(1);
        user.setName("库里");
        return user;
    }

    /**
     * 有一个引用类型的参数
     *
     * @param user
     * @return
     */
    @RequestMapping(value = "/add", method = RequestMethod.POST)
    @ApiOperation(value = "添加用户", notes = "添加一个新的用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体", required = true, dataType = "User")
    public String postBook(@RequestBody User user) {
        System.out.println(user);
        return "添加用户成功";
    }


    /**
     * 有一个简单类型的参数和一个引用类型的参数
     *
     * @param id
     * @param user
     * @return
     */
    @RequestMapping(value = "/update/{id}", method = RequestMethod.PUT)
    @ApiOperation(value = "更新信息", notes = "根据url的id来指定更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User")
    })
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        System.out.println(id);
        System.out.println(user.getId());
        System.out.println(user.getName());
        return "修改成功";
    }

    /**
     * 有一个Long的参数
     *
     * @param id
     * @return
     */
    @RequestMapping(value = "/del_user/{id}", method = RequestMethod.DELETE)
    @ApiOperation(value = "删除用户", notes = "根据id来删除指定用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    public String deleteUser(@PathVariable Long id) {
        System.out.println("删除用户：" + id);
        return "success";
    }

    /**
     * 使用该注解忽略这个API
     *
     * @return
     */
    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    @ApiIgnore
    public String jsonTest() {
        return " hi you!";
    }


    @ApiOperation("更改用户信息")
    @PostMapping("/updateUserInfo")
    public int test(@RequestBody @ApiParam(name = "用户对象", value = "传入json格式", required = true) User user) {
        return 1;
    }
}

最后运行项目，然后在浏览器中打开 http://localhost:8080/swagger-ui.html

看到如下界面

image.png

完整代码

https://github.com/xiaozhaowen/spring-boot-in-action/tree/master/springboot-swagger2