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 执行后,返回接口执行结果:

 

 

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值