目录
简介
整合到Spring Boot中，构建强大RESTful API文档。省去接口文档管理工作，修改代码，自动更新，Swagger2也提供了强大的页面测试功能来调试RESTful API。
pom 依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
配置类
@Configuration
@EnableSwagger2
public class Swagger2 {
/**
* 通过 createRestApi函数来构建一个DocketBean
* 函数名,可以随意命名,喜欢什么命名就什么命名
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
.select()
//控制暴露出去的路径下的实例
//如果某个接口不想暴露,可以使用以下注解
//@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下
.apis(RequestHandlerSelectors.basePackage("com.example.zwd.springbootswagger2.controller"))
.paths(PathSelectors.any())
.build();
}
//构建 api文档的详细信息函数
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("Spring Boot Swagger2 构建RESTful API")
//条款地址
.termsOfServiceUrl("http://despairyoke.github.io/")
.contact("zwd")
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
配置文件
开发环境一般是开启, 生产环境一般是关闭
- application.yml
# swagger 开启或者关闭;
swagger:
enable: true
- application.properties
#是否激活 swagger true or false
swagger.enable=true
Swagger注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
- @Api：修饰整个类，描述Controller的作用
- @ApiOperation：描述一个类的一个方法，或者说一个接口
- @ApiParam：单个参数描述
- @ApiModel：用对象来接收参数
- @ApiProperty：用对象接收参数时，描述对象的一个字段
- @ApiResponse：HTTP响应其中1个描述
- @ApiResponses：HTTP响应整体描述
- @ApiIgnore：使用该注解忽略这个API
- @ApiError ：发生错误返回的信息
- @ApiImplicitParam：一个请求参数
- @ApiImplicitParams：多个请求参数
swagger2 注解整体说明
- 用于controller类上：
| 注解 | 说明 |
|---|---|
| @Api | 对请求类的说明 |
- 用于方法上面（说明参数的含义）：
| 注解 | 说明 |
|---|---|
| @ApiOperation | 方法的说明 |
| @ApiImplicitParams、@ApiImplicitParam | 方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明 |
- 用于方法上面（返回参数或对象的说明）：
| 注解 | 说明 |
|---|---|
| @ApiResponses、@ApiResponse | 方法返回值的说明 ；@ApiResponses 用于指定单个参数的说明 |
- 对象类：
| 注解 | 说明 |
|---|---|
| @ApiModel | 用在JavaBean类上，说明JavaBean的 用途 |
| @ApiModelProperty | 用在JavaBean类的属性上面，说明此属性的的含议 |
@Api：请求类的说明
@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags="说明该类的作用"
value="该参数没什么意义，所以不需要配置"
示例：
@Api(tags="订单模块")
@Controller
public class OrderController {
}
@Api 其它属性配置：
| 属性名称 | 备注 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | 如, “application/json, application/xml” |
| consumes | 如, “application/json, application/xml” |
| protocols | 协议类型，如: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true ，将在文档中隐藏 |
@ApiOperation：方法的说明
@ApiOperation："用在请求的方法上，说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
@ApiImplicitParams、@ApiImplicitParam：方法参数的说明
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的说明、描述
required：参数是否必须必填
paramType：参数放在哪个地方
· query --> 请求参数的获取：@RequestParam
· header --> 请求参数的获取：@RequestHeader
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（请求体）--> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public JsonResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//...
return JsonResult.ok(map);
}
}
@ApiResponses、@ApiResponse：方法返回值的状态码说明
@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
// 示例：
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation("获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
})
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ResponseBody
@RequestMapping("/list")
public JsonResult list(@RequestParam String userId) {
...
return JsonResult.ok().put("page", pageUtil);
}
}
@ApiModel：用于JavaBean上面，表示对JavaBean 的功能描述
@ApiModel的用途有2个：
当请求数据描述，即 @RequestBody 时， 用于封装请求（包括数据的各种校验）数据；
当响应值是对象时，即 @ResponseBody 时，用于返回值对象的描述。
- 1、当请求数据描述时， @RequestBody 时的使用
@ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "用户名",required=true)
private String username;
@ApiModelProperty(value = "密码",required=true)
private String password;
// getter/setter省略
}
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value = "用户登录", notes = "")
@PostMapping(value = "/login")
public R login(@RequestBody UserLoginVO userLoginVO) {
User user=userSerivce.login(userLoginVO);
return R.okData(user);
}
}
- 2、@ApiModelProperty：用在JavaBean类的属性上面，说明属性的含义
示例:
@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{
@ApiModelProperty(value = "是否成功",required=true)
private boolean success=true;
@ApiModelProperty(value = "错误码")
private Integer errCode;
@ApiModelProperty(value = "提示信息")
private String message;
@ApiModelProperty(value = "数据")
private Object data;
/* getter/setter 略*/
}
访问Swagger2文档
启动SpringBoot项目，访问 http://localhost:8080/swagger-ui.html