SpringBoot入门教程六：Springboot集成Swagger2

Swagger2简介

Swagger2是Api接口文档生成工具，它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：

1. 接口文档在线自动生成，文档随接口变动实时更新，节省维护成本

2. 支持在线接口测试，不依赖第三方工具

 

步骤

（1）在pom.xml文件中引入相关依赖；

（2）创建Swagger2配置类Swagger2Configuration ;

（3）编写API测试接口;

（4）启动Springboot应用，查看接口文档；

（5）测试接口。

 

 

>>>>>>>>>>>>>>>>>>>>>开始>>>>>>>>>>>>>>>>>>>>>>>>

1、加入相关依赖

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

 

2、创建Swagger2配置类Swagger2Configuration 

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    //api接口包扫描路径
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "org.lee.springboot";

    public static final String VERSION = "1.0.0";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger测试") //设置文档的标题
                .description("swagger测试 API 接口文档") // 设置文档的描述
                .version(VERSION) // 设置文档的版本信息
                .termsOfServiceUrl("http://www.csdn.net") //条款地址
                .license("The Apache License")//设置文档的License信息
                .build();
    }
}

 

3、编写API测试接口

@Api("用户接口")
@RestController
public class UserController {

    @Resource
    private UserService userService;

    @ApiOperation(value = "通过用户名查询用户信息", notes = "通过用户名查询用户信息", produces = "application/json")
    @ApiImplicitParam(name = "name", value = "用户名", paramType = "query", required = true, dataType = "String")
    @RequestMapping(value = "user/name", method = {RequestMethod.GET, RequestMethod.POST})
    public User getUser(String name) {
        User user = userService.selectUserByName(name);
        return user;
    }

    @ApiOperation(value = "通过用户ID查询用户信息", notes = "通过用户ID查询用户信息", produces = "application/json")
    @ApiImplicitParam(name = "id", value = "用户ID", paramType = "query", required = true, dataType = "int", example="0")
    @RequestMapping(value = "user/id", method = {RequestMethod.GET, RequestMethod.POST})
    public User getUser(Integer id) {
        User user = userService.selectUserById(id);
        return user;
    }

    @ApiOperation(value = "通过用户年龄查询用户信息", notes = "通过用户年龄查询用户信息", produces = "application/json")
    @ApiImplicitParam(name = "age", value = "用户年龄", paramType = "query", required = true, dataType = "int", example="0")
    @RequestMapping(value = "user/age", method = {RequestMethod.GET, RequestMethod.POST})
    public List<User> getUserByAge(Integer age) {
        PageHelper.startPage(1, 2);
        List<User> users = userService.selectUserByAge(age);
        return users;
    }

    @ApiOperation(value = "新增用户", notes = "新增用户", produces = "application/json")
    @ApiImplicitParams({@ApiImplicitParam(name = "name", value = "用户名", paramType = "query", required = true, dataType = "String")
            , @ApiImplicitParam(name = "age", value = "用户年龄", paramType = "query", required = true, dataType = "int", example="0")})
    @RequestMapping(value = "user/add", method = RequestMethod.POST)
    public User addUser(String name, Integer age) {
        User user = new User();
        user.setName(name);
        user.setAge(age);
        userService.insertUser(user);
        return user;
    }

    @ApiIgnore // 忽略这个API
    @ApiOperation(value = "批量新增用户", notes = "批量新增用户", produces = "application/json")
    @RequestMapping(value = "user/add/batch", method = RequestMethod.POST)
    public List<User> addUsers(@RequestBody List<User> users) {
        userService.batchInsertUser(users);
        return users;
    }

}

 

如果传入的参数是对象，需要在对象的属性上加@ApiModelProperty注解

import io.swagger.annotations.ApiModelProperty;

public class User {

	@ApiModelProperty("用户ID")
	private Integer id;

	@ApiModelProperty("用户名")
	private String name;

	@ApiModelProperty("用户年龄")
	private Integer age;

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

	public Integer getAge() {
		return age;
	}

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

}

 

Swagger 通过注解定制接口对外展示的信息，这些信息包括接口名、请求方法、参数、返回信息等。

注解如下：

* @Api：修饰整个类，描述Controller的作用
* @ApiOperation：描述一个类的一个方法，或者说一个接口
* @ApiParam：单个参数描述
* @ApiModel：用对象来接收参数
* @ApiProperty：用对象接收参数时，描述对象的一个字段
* @ApiResponse：HTTP响应其中1个描述
* @ApiResponses：HTTP响应整体描述
* @ApiIgnore：使用该注解忽略这个API
* @ApiError ：发生错误返回的信息
* @ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
* @ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

 

4、启动Springboot应用

启动成功后，访问 http://localhost:8080/swagger-ui.html，如图所示：

 

5、测试接口

点击其中一个接口进行测试：

点击Try it out按钮：

Execute 执行后，返回接口执行结果：