Swagger2基本注解介绍

2023-11-14 09:33:28

一. 前言

小熙在使用Swagger2的时候，喜欢和 Validated 注解一起使用，当然 valid 也不错。
以下 Api 开头的注解请注意，以及看清使用的位置。

二. 代码演示

controller中代码

package com.uthink.member.controller.cy;

import com.uthink.member.entity.common.ResponseEntity;
import com.uthink.member.entity.vo.cy.SwaggerTestVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import lombok.extern.slf4j.Slf4j;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import javax.validation.constraints.NotNull;

/**
 * @author chengxi
 * @date 2020/2/22
 */
@Api(tags = "a_swaggerTestController")
@Slf4j
@RestController
@RequestMapping(value = "/swaggerTest")
public class SwaggerTestController {

    @ApiOperation(value = "swaggerTestGetMethod")
    @GetMapping
    public ResponseEntity<SwaggerTestVO> testGetIndex(@ApiParam @Validated SwaggerTestVO swaggerTestVO){

        return ResponseEntity.success(swaggerTestVO,"accessSuccessful");
    }

    @ApiOperation(value = "swaggerTestPostMethod")
    @PostMapping
    public ResponseEntity<SwaggerTestVO> testPostIndex(@ApiParam @Validated @RequestBody SwaggerTestVO swaggerTestVO){

        return ResponseEntity.success(swaggerTestVO,"accessSuccessful");
    }

    @ApiOperation(value = "swaggerTestPutMethod/{id}")
    @PutMapping
    public ResponseEntity<Integer> testPutIndex(@ApiParam(value = "学生id", required = true) @NotNull @PathVariable Integer id){

        return ResponseEntity.success(id,"accessSuccessful");
    }

    @ApiOperation(value = "swaggerTestDeleteMethod/{id}")
    @DeleteMapping
    public ResponseEntity<Integer> testDeleteIndex(@ApiParam(value = "学生id", required = true) @NotNull @PathVariable Integer id){

        return ResponseEntity.success(id,"accessSuccessful");
    }



}

vo中代码

package com.uthink.member.entity.vo.cy;

import com.uthink.member.validator.Phone;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.validation.annotation.Validated;

import javax.validation.constraints.*;
import java.time.LocalDateTime;

/**
 * @author chengxi
 * @date 2020/2/22
 * 
 *  Validated 注解这里只是介绍了部分，下面会附上详解
 */
@Data
@ApiModel(value = "SwaggerTestModelVO")
@Validated
public class SwaggerTestVO {

    /**
     * @NotBlank 字符串不能为空
     */
    @NotBlank
    @ApiModelProperty(value = "名称", required = true, dataType = "String")
    private String name;

    /**
     * @Min(value = 0)     最小值为0
     * @Max(value = 100)   最大值为100
     */
    @Min(value = 0)
    @Max(value = 100)
    @ApiModelProperty(value = "年龄", example = "18")
    private Integer age;

    /**
     * @NotNull    包装类，不能为空
     */
    @NotNull
    @ApiModelProperty(value = "年级数", required = true, example = "2")
    private Integer classNum;

    /**
     * @Email       验证邮箱是否正确
     */
    @Email
    @ApiModelProperty(value = "学校邮箱")
    private String schoolEmail;

    /**
     * @Size(min = 9, max = 18)    集合（容器）长度最小为9, 最大长度为18
     */
    @Size(min = 9, max = 18)
    @ApiModelProperty(value = "邮箱密码")
    private String emailPassword;

    /**
     * @Future   与当前时间比较，在这个时间之后
     */
    @Future
    @ApiModelProperty(value = "开学日期")
    private LocalDateTime startDateTime;

    /**
     * @Phone 是自定义注解，验证手机号是否正确
     */
    @Phone
    @ApiModelProperty(value = "手机号")
    private String phone;


    @ApiModelProperty(value = "测试隐藏值", hidden = true)
    private String hiddenString;
}

自定义注解代码

package com.uthink.member.validator;

import org.hibernate.validator.constraints.CompositionType;
import org.hibernate.validator.constraints.ConstraintComposition;
import org.hibernate.validator.constraints.Length;
import javax.validation.Constraint;
import javax.validation.Payload;
import javax.validation.ReportAsSingleViolation;
import javax.validation.constraints.Null;
import javax.validation.constraints.Pattern;
import java.lang.annotation.*;

/**
 * @author chengxi
 * @date 2020/2/22
 *
 *
 * 测试手机号校验注解，如果不符合业务，请根据自己的业务重新设计，这里只是提供自己创建注解介绍
 */
@ConstraintComposition(CompositionType.OR)
@Pattern(regexp = "^((13[0-9])|(14[5,7,9])|(15([0-3]|[5-9]))|(166)|(17[0,1,3,5,6,7,8])|(18[0-9])|(19[8|9]))\\\\d{8}$")
@Null
@Length(min = 0, max = 0)
@Documented
@Constraint(validatedBy = {})
@Target({ ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.PARAMETER })
@Retention(RetentionPolicy.RUNTIME)
@ReportAsSingleViolation
public @interface Phone {
    String message() default "手机号校验错误";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}

三. 界面如图

1. 全景

2. Get请求

（1）
（2）

（3）

（4）

3. post 请求

4. put 请求

5. delete 请求

四. Validated 部分标签含义

限制	说明
@Null	限制只能为null
@NotNull	限制必须不为null
@AssertFalse	限制必须为false
@AssertTrue	限制必须为true
@DecimalMax(value)	限制必须为一个不大于指定值的数字
@DecimalMin(value)	限制必须为一个不小于指定值的数字
@Digits(integer,fraction)	限制必须为一个小数，且整数部分的位数不能超过integer，小数部分的位数不能超过fraction
@Future	限制必须是一个将来的日期
@Max(value)	限制必须为一个不大于指定值的数字
@Min(value)	限制必须为一个不小于指定值的数字
@Past	限制必须是一个过去的日期
@Pattern(value)	限制必须符合指定的正则表达式
@Size(max,min)	限制字符长度必须在min到max之间
@Past	验证注解的元素值（日期类型）比当前时间早
@NotEmpty	验证注解的元素值不为null且不为空（字符串长度不为0、集合大小不为0）
@NotBlank	验证注解的元素值不为空（不为null、去除首位空格后长度为0），不同于@NotEmpty，@NotBlank只应用于字符串且在比较时会去除字符串的空格
@Email	验证注解的元素值是Email，也可以通过正则表达式和flag指定自定义的email格式

以前就是 swagger2 和 Validated 注解的基础使用了，想深入了解可以查查。

程熙cjp 发布了47 篇原创文章 · 获赞 164 · 访问量 5万+ 私信关注

码农公寓

一. 前言

二. 代码演示

三. 界面如图

四. Validated 部分标签含义

相关文章