SpringBoot整合Swagger实现接口文档

在项目开发中，一般都是前后端分离开发的，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发、维护。

为了便于编写和维护稳定，可以使用Swagger来编写API接口文档，以提升团队的沟通效率。

【示例】SpringBoot整合Swagger实现接口文档。

1、配置Swagger

（1）添加Swagger依赖。

在pop.xml文件中加入Swagger2的依赖，配置如下：

<!--Swagger依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!--Swagger-UI依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

（2）创建Swagger配置类。

创建Swagger配置类，完成相关配置项。

package com.pjb.config;

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;

/**
 * Swagger 配置类
 * @author pan_junbiao
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig
{
    /**
     * 创建API应用
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.pjb.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(" RESTful APIs")
                .description("RESTful APIs")
                .termsOfServiceUrl("http://localhost:8080/")
                .contact("long")
                .version("1.0")
                .build();
    }
}

2、编写接口文档

在完成上述配置后，即生成了文档，但是这样生成的文档主要针对请求本身，而描述自动根据方法等命名产生，对用户并不友好。所以，通常需要自己增加一些说明以丰富文档内容。可以通过以下注解来增加说明。

@Api：描述类/接口的主要用途，用在类（控制器类）上。

@ApiOperation：描述方法用途，给API增加说明，用在方法上。

@ApiImplicitParam：描述方法的参数，给参数增加说明。

@ApiImplicitParams：描述方法的参数( Multi-Params)，给参数增加说明。

@ApiIgnore：忽略某类/方法/参数的文档。

具体使用方法见如下：

/**
 * 删除用户信息
 * @author pan_junbiao
 */
@ApiOperation(value="删除用户信息",notes="根据URL的id来指定删除的用户信息")
@ApiImplicitParam(name="id",value = "用户ID", required = true, dataType = "int")
@RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
public ApiResultModel deleteUserInfo(@PathVariable("id")int userId)
{
    //删除用户信息
    userDao.deleteById(userId);

    //返回结果
    ApiResultModel apiResultModel = new ApiResultModel();
    apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
    apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
    apiResultModel.data = true;
    return apiResultModel;
}

完整的实例代码：

package com.pjb.controller;

import com.pjb.dao.UserDao;
import com.pjb.entity.UserInfo;
import com.pjb.model.ApiResultModel;
import com.pjb.model.ApiStatusCode;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * 用户信息控制器
 * @author pan_junbiao
 **/
@Api(description = "用户信息控制器")
@RestController
@RequestMapping("user")
public class UserController
{
    @Autowired
    private UserDao userDao;

    /**
     * 获取用户列表
     */
    @ApiOperation(value="获取用户列表",notes="获取所有用户信息列表")
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public ApiResultModel getUserList()
    {
        //获取用户列表
        List<UserInfo> userInfoList = userDao.findAll();

        //返回结果
        ApiResultModel apiResultModel = new ApiResultModel();
        apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
        apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
        apiResultModel.data = userInfoList;
        return apiResultModel;
    }

    /**
     * 获取用户信息
     */
    @ApiOperation(value="获取用户信息",notes="根据URL的id来指定获取的用户信息")
    @ApiImplicitParam(name="id",value = "用户ID", required = true, dataType = "int")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    public ApiResultModel getUserInfo(@PathVariable("id")int userId)
    {
        //根据用户ID，获取用户信息
        UserInfo userInfo = userDao.findById(userId).orElse(null);

        //返回结果
        ApiResultModel apiResultModel = new ApiResultModel();
        apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
        apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
        apiResultModel.data = userInfo;
        return apiResultModel;
    }

    /**
     * 新增用户信息
     */
    @ApiOperation(value="新增用户信息")
    @RequestMapping(value = "/", method = RequestMethod.POST)
    public ApiResultModel addUser(@RequestBody UserInfo userInfo)
    {
        //参数验证
        if(userInfo.getUserName()==null || userInfo.getUserName().length()==0)
        {
            //返回参数缺失
            ApiResultModel apiResultModel = new ApiResultModel();
            apiResultModel.statusCode = ApiStatusCode.PARAM_INVALID.getCode();
            apiResultModel.message = ApiStatusCode.PARAM_INVALID.getDescription();
            apiResultModel.data = false;
            return apiResultModel;
        }

        //新增用户信息
        userDao.save(userInfo);

        //返回结果
        ApiResultModel apiResultModel = new ApiResultModel();
        apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
        apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
        apiResultModel.data = true;
        return apiResultModel;
    }

    /**
     * 修改用户信息
     */
    @ApiOperation(value="修改用户信息",notes="根据URL的id来指定修改的用户信息")
    @ApiImplicitParam(name="id",value = "用户ID", required = true, dataType = "int")
    @RequestMapping(value = "/", method = RequestMethod.PUT)
    public ApiResultModel updateUser(@RequestBody UserInfo userInfo)
    {
        //参数验证
        if(userInfo.getUserId()<=0 || userInfo.getUserName()==null || userInfo.getUserName().length()==0)
        {
            //返回参数缺失
            ApiResultModel apiResultModel = new ApiResultModel();
            apiResultModel.statusCode = ApiStatusCode.PARAM_INVALID.getCode();
            apiResultModel.message = ApiStatusCode.PARAM_INVALID.getDescription();
            apiResultModel.data = false;
            return apiResultModel;
        }

        //修改用户信息
        userDao.save(userInfo);

        //返回结果
        ApiResultModel apiResultModel = new ApiResultModel();
        apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
        apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
        apiResultModel.data = true;
        return apiResultModel;
    }

    /**
     * 删除用户信息
     */
    @ApiOperation(value="删除用户信息",notes="根据URL的id来指定删除的用户信息")
    @ApiImplicitParam(name="id",value = "用户ID", required = true, dataType = "int")
    @RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
    public ApiResultModel deleteUserInfo(@PathVariable("id")int userId)
    {
        //删除用户信息
        userDao.deleteById(userId);

        //返回结果
        ApiResultModel apiResultModel = new ApiResultModel();
        apiResultModel.statusCode = ApiStatusCode.SUCCESS.getCode();
        apiResultModel.message = ApiStatusCode.SUCCESS.getDescription();
        apiResultModel.data = true;
        return apiResultModel;
    }
}

3、运行测试

完成上述代码后，启动项目，访问 http://127.0.0.1:8080/swagger-ui.html 就能看到所展示的RESTful API的页面，可以通过单击具体的API测试请求，来查看代码中配置的信息，以及参数的描述信息。

点击测试，获取用户信息，执行结果如下：