springboot2.x集成swagger2（笔记）

100 阅读 0 评论 66 点赞

我是靠谱客的博主霸气铃铛，这篇文章主要介绍springboot2.x集成swagger2（笔记），现在分享给大家，希望可以做个参考。

GitHub地址：
https://github.com/dyc87112/spring-boot-starter-swagger

1、在pom.xml中导入swagger2的依赖

复制代码

1
2
3
4
5
6
 <dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.1.RELEASE</version>
</dependency>

说明：

复制代码

1
2
3
从1.6.0开始，我们按Spring Boot官方建议修改了artifactId为swagger-spring-boot-starter，1.6.0之前的版本不做修改，依然为使用spring-boot-starter-swagger !**
从2.0.0开始，不再需要手工添加@EnableSwagger2Doc来启动Swagger配置

2、开启swagger2的功能

复制代码

1
2
3
4
5
6
7
8
@SpringBootApplication
@EnableSwagger2Doc
public class MybatisPlusTestApplication {
public static void main(String[] args) {
SpringApplication.run(MybatisPlusTestApplication.class, args);
}
}

3、参数配置

复制代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
springfox.documentation.enabled=true
#是否启用swagger，默认：true
swagger.title=spring-boot-starter-swagger
#标题
swagger.description=Starter for swagger 2.x
#描述
swagger.version=1.4.0.RELEASE
#版本
swagger.license=Apache License, Version 2.0
#许可证
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
#服务条款URL
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
#服务条款URL
swagger.contact.name=didi
#服务条款URL
swagger.contact.url=http://blog.didispace.com
#维护人URL
swagger.contact.email=dyc87112@qq.com
#维护人URL
swagger.base-package=com.didispace
#swagger扫描的基础包，默认：全扫描
swagger.base-path=/**
#需要处理的基础URL规则，默认：/**
swagger.exclude-path=/error, /ops/**
#需要处理的基础URL规则，默认：/**

4、常用注解

@Api
作用在controller类上面。

复制代码

1
2
3
4
5
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {

@ApiOperation
作用在controller方法上面，描述方法作用。

复制代码

1
2
3
4
@GetMapping("{id}")
@ApiOperation(value = "查询用户", notes = "根据用户ID查询用户信息", response = User.class)
public User getUser(@PathVariable("id") String id) {

@ApiParam
作用在controller上面，对请求参数说明。

复制代码

1
2
3
@GetMapping("{id}")
public User getUser(@PathVariable("id") @ApiParam(name = "id", value = "用户ID", required = true) String id) {

@ApiResponse
作用在controller上面，方法返回描述

复制代码

1
2
3
4
@GetMapping("{id}")
@ApiResponse(code = 200, response = User.class, message = "用户信息对象")
public User getUser(@PathVariable("id") String id) {

@ApiResponses
作用在controller上面，对返回参数参数描述

@ApiImplicitParam
作用在controller上面，对单个请求参数描述

复制代码

1
2
3
4
@GetMapping("{id}")
@ApiImplicitParam(name = "id",value = "用户ID",dataType = "String",paramType = "path",required = true)
public User getUser(@PathVariable("id") @ApiParam(name = "id", value = "用户ID", required = true) String id) {

@ApiModel
作用在javaBan类上面，对类进行描述

复制代码

1
2
3
@ApiModel(description = "用户实体类")
public class User implements Serializable {

@ApiModelProperty
做用在javaBean属性上面，对熟悉进行描述

复制代码

1
2
3
4
@ApiModelProperty(value = "用户ID")
@TableId(type = IdType.AUTO)
private Long id;

@ResponseHeader
作用在controller上面，对响应头描述

controller类

复制代码

package com.example.mybatisplustest.controller;
import com.example.mybatisplustest.pojo.User;
import com.example.mybatisplustest.server.UsreService;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {
@Autowired
private UsreService usreService;
@GetMapping("{id}")
@ApiOperation(value = "查询用户", notes = "根据用户ID查询用户信息", response = User.class)
@ApiImplicitParam(name = "id", value = "用户ID", required = true)
public User getUser(@PathVariable String id) {
return usreService.getById(id);
}
@PostMapping()
@ApiOperation(value = "添加用户", notes = "添加用户信息", response = Boolean.class)
@ApiImplicitParam(name = "user", value = "用户实体类")
public boolean saveUser(@RequestBody User user) {
return usreService.save(user);
}
@PutMapping()
@ApiOperation(value = "修改用户", notes = "修改用户信息", response = Boolean.class)
@ApiImplicitParam(name = "user", value = "用户实体类")
public boolean updateUser(@RequestBody User user) {
System.out.println(user);
return usreService.updateById(user);
}
@DeleteMapping("/{id}")
@ApiOperation(value = "删除用户", notes = "删除用户信息", response = Boolean.class)
@ApiImplicitParam(name = "id", value = "用户ID")
public boolean deleteUser(@PathVariable String id) {
return usreService.removeById(id);
}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
package com.example.mybatisplustest.controller;
import com.example.mybatisplustest.pojo.User;
import com.example.mybatisplustest.server.UsreService;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {
@Autowired
private UsreService usreService;
@GetMapping("{id}")
@ApiOperation(value = "查询用户", notes = "根据用户ID查询用户信息", response = User.class)
@ApiImplicitParam(name = "id", value = "用户ID", required = true)
public User getUser(@PathVariable String id) {
return usreService.getById(id);
}
@PostMapping()
@ApiOperation(value = "添加用户", notes = "添加用户信息", response = Boolean.class)
@ApiImplicitParam(name = "user", value = "用户实体类")
public boolean saveUser(@RequestBody User user) {
return usreService.save(user);
}
@PutMapping()
@ApiOperation(value = "修改用户", notes = "修改用户信息", response = Boolean.class)
@ApiImplicitParam(name = "user", value = "用户实体类")
public boolean updateUser(@RequestBody User user) {
System.out.println(user);
return usreService.updateById(user);
}
@DeleteMapping("/{id}")
@ApiOperation(value = "删除用户", notes = "删除用户信息", response = Boolean.class)
@ApiImplicitParam(name = "id", value = "用户ID")
public boolean deleteUser(@PathVariable String id) {
return usreService.removeById(id);
}
}

user类

复制代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
package com.example.mybatisplustest.pojo;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.ToString;
import java.io.Serializable;
import java.util.List;
@Data
@NoArgsConstructor
@AllArgsConstructor
@TableName("user")
@ToString
@ApiModel(description = "用户实体类")
public class User implements Serializable {
@ApiModelProperty(value = "用户ID")
@TableId(type = IdType.AUTO)
private Long id;
@ApiModelProperty(value = "用户姓名")
private String name;
@ApiModelProperty(value = "用户地址集合")
@TableField(exist = false)
private List<Address> addressList;
}