在开发过程中，为了实现前后端高效的沟通，通常需要提供相关的接口文档。
Swagger2可以轻松的整合到SpringBoot中，并与SpringMVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，也可以让我们在修改代码逻辑的同时修改文档说明。此外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。
本文主要介绍Spring Boot 2.0 与 Swagger2的整合。
一、swagger 注解
@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：用于类上，表示一组数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述属性
二、添加依赖
<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>
三、配置Swagger
package pers.simon.boot.validator.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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* swagger2 配置
*
* @author simon
* @date 2019/12/12 13:57
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 实例化一个 Docket Bean
* <p></p>
* <b>
* 这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等
* </b>
*
* @return Docket Bean
*/
@Bean
public Docket createDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")//默认请求都是以 / 根路径开始，如果我们的应用不是部署在根路径，比如以/validator部署，则可以通过一下方式设置请求的统一前缀
.select()
.apis(RequestHandlerSelectors.basePackage("pers.simon.boot.validator.controller"))//
.paths(PathSelectors.any())
.build()
.apiInfo(new ApiInfoBuilder()
.title("Spring Boot 参数校验")
.description("使用 validator 对入参进行校验。包含自定义规则校验，分组校验，全局异常处理等")
.version("1.0.0")
.contact(new Contact("simon", "www.baidu.com", "simon@126.com"))
.license("The Apache License")
.licenseUrl("www.baidu.com")
.build()
);
}
}
四、接口
package pers.simon.boot.validator.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import pers.simon.boot.validator.annotate.Create;
import pers.simon.boot.validator.annotate.Update;
import pers.simon.boot.validator.po.UserVo;
import pers.simon.boot.validator.utils.JsonResult;
import javax.validation.constraints.NotEmpty;
/**
*
* @author simon
* @date 2019/12/10 10:39
*/
@Api(tags = "用户管理")
@RestController
@Validated
public class UserController {
@ApiOperation("添加用户")
@PostMapping("/user")
@ApiImplicitParam(name = "userVo", value = "用户信息表单", required = true, dataType = "UserVo")
public JsonResult saveUser(@RequestBody @Validated(Create.class) UserVo userVo){
return JsonResult.success(userVo);
}
@ApiOperation("修改用户")
@ApiImplicitParam(name = "userVo", value = "用户信息表单", required = true, dataType = "UserVo")
@PutMapping("/user")
public JsonResult updateUser(@RequestBody @Validated(Update.class) UserVo userVo){
return JsonResult.success(userVo);
}
@ApiOperation("注销用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId",value = "用户ID",defaultValue = "",required = true),
@ApiImplicitParam(name = "deptId",value = "部门ID",defaultValue = "",required = true)
})
@PatchMapping("/user")
public JsonResult disableUser(@NotEmpty(message = "用户ID不能为空")String userId, @NotEmpty(message = "所属部门ID不能为空")String deptId){
return JsonResult.success(userId);
}
}
入参UserVo
package pers.simon.boot.validator.po;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import pers.simon.boot.validator.annotate.Create;
import pers.simon.boot.validator.annotate.IdCard;
import pers.simon.boot.validator.annotate.Update;
import javax.validation.constraints.*;
import java.util.Date;
/**
* @author simon
* @date 2019/12/10 10:28
*/
@ApiModel(description = "用户信息表单")
@Data
public class UserVo {
@ApiModelProperty(value = "用户ID", name = "userId", required = true, example = "123")
@Null(message = "用户ID必须为空",groups = Create.class)
@NotBlank(message = "用户ID不能为空",groups = Update.class)
private String userId;
@ApiModelProperty(value = "用户名称", name = "userName", required = true, example = "admin")
@NotBlank(message = "用户名不能为空")
private String userName;
@ApiModelProperty(value = "生日", name = "birthday", required = true, example = "2019-11-02")
@Past(message = "生日必须为过去日期")
@NotNull(message = "生日不能为空")
private Date birthday;
@ApiModelProperty(value = "年龄", name = "age", required = true, example = "11", dataType = "int")
@Min(value = 10,message = "年龄必须大于10")
@Max(value = 30,message = "年龄必须小于30")
@NotNull(message = "年龄不能为空")
private Integer age;
@ApiModelProperty(value = "邮箱", name = "email", required = true, example = "11@qq.com")
@NotBlank(message = "邮箱不能为空")
@Email(message = "邮箱格式错误")
private String email;
@ApiModelProperty(value = "手机号", name = "phone", required = true, example = "12345678900")
@NotNull(message = "手机号不能为空")
@NotBlank(message = "手机号不能为空")
@Pattern(regexp ="^[1][3,4,5,6,7,8,9][0-9]{9}$", message = "手机号格式有误")
@Max(value = 11,message = "手机号只能为11位")
@Min(value = 11,message = "手机号只能为11位")
private String phone;
@ApiModelProperty(value = "身份证号", name = "idCard", required = true, example = "12345678900")
@NotBlank(message = "身份证不能为空")
@IdCard(message = "身份证不合法")
private String idCard;
}
六、测试
访问：http://localhost:8080/swagger-ui.html
2aa6d12ee2d2ad060698cce87e45a6c.png
网友评论