常用Swagger注解汇总

前言

  在实际编写后端代码的过程中，我们可能经常使用到 swagger 注解，但是会用不代表了解，你知道每个注解都有什么属性吗？你都用过这些属性吗？了解它们的作用吗？本文在此带大家总结一下常用的swagger注解，供大家学习理解。

控制器层

@Api

介绍

  此注解应用于类、接口或者枚举上，启动应用时被标注的类会扫描到 swagger 源中。默认情况下，swagger 核心仅扫描带有 @Api 注解的类而无视其他的源数据 (例如：JAX-RS 端口、Serlvet 等等)

  不能标注在方法上且一般不单独使用，常见的做法是搭配 @ApiOperation 注解，作为业务接口类的说明。

源码

package io.swagger.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Api {
    
    String value() default "";

    String[] tags() default "";

    @Deprecated String description() default "";

    @Deprecated String basePath() default "";

    @Deprecated int position() default 0;

    String produces() default "";

    String consumes() default "";
    
    String protocols() default "";
    
    Authorization[] authorizations() default @Authorization(value = "");

    boolean hidden() default false;
}

属性

  从源码我们可以看到 @Api 注解除了已废弃的3个，共有 7 个属性，不过这里面只有下面这1个属性比较常用：

1、tags (接口业务所属分组)

这是一个用于控制 API 文档标签的列表，标签可按资源或者其他标识符对操作进行分组。该属性就是对实现相同业务功能的接口类做一个大致的分组，该分组中包括相同业务功能下的所有接口。

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 测试方法
     */
    @ApiOperation("测试方法")
    @GetMapping("/test")
    public R<Void> testApi(){
        System.out.println("Hello,world");
        return ok();
    }
}

说完了常用的属性，我们再来补充一下剩下的一些不常用属性：

@ApiOperation

介绍

  @ApiOperation 注解可应用于方法或类上，通常标注在方法上作为业务接口的名称，描述其操作或者描述针对于特定路径的 HTTP 方法。默认情况下，具有相同效果的操作被分组在一个单独的操作对象中，而 HTTP 方法和路径的组合将会创建一个独一无二的操作。此外，此注解提供了丰富的属性来允许我们自定义接口的描述信息，包括接口名称和所属分组等。

源码

package io.swagger.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiOperation {

    String value();

    String notes() default "";

    String[] tags() default "";

    Class<?> response() default Void.class;

    String responseContainer() default "";

    String responseReference() default "";

    String httpMethod() default "";

    @Deprecated int position() default 0;

    String nickname() default "";

    String produces() default "";

    String consumes() default "";

    String protocols() default "";

    Authorization[] authorizations() default @Authorization(value = "");

    boolean hidden() default false;

    ResponseHeader[] responseHeaders() default @ResponseHeader(name = "", response = Void.class);

    int code() default 200;

    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));

    boolean ignoreJsonView() default false;
}

属性

  从源码我们可以看到 @ApiOperation 注解除了已废弃的1个，共有 17 个属性。不过这里面只有以下 2 个属性比较常用：

1、value (接口名称)

对应操作的摘要字段。此属性提供接口的简要描述（即接口说明），最多 120 个字符或者少于 Swagger-UI 页面可展示的。

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 获取信息
     */
    @ApiOperation("获取信息")
    @GetMapping("/getInfo")
    public R<Integer> getInfo() {
        int i = 1;
        return R.ok(i);
    }
}

2、notes (接口描述)

对应操作的详情字段。这是一段冗长的操作描述，没有字数限制，通常适用于当 value 属性无法解释清楚时对接口操作的补充说明。

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 获取信息
     */
    @ApiOperation(value = "获取信息", notes = "用于获取信息的接口")
    @GetMapping("/getInfo")
    public R<Integer> getInfo() {
        int i = 1;
        return R.ok(i);
    }
}

说完了常用的属性，我们再来补充一下剩下的一些不常用属性：

@ApiImplicitParam

前言

  此注解只能标注在方法上，代表了方法中的一个独立的参数，如果方法有多个参数，可以和 @ApiImplicitParams 注解搭配使用。

  当 ApiParam 注解绑定了一个 JAX-RS 的参数、方法、或者字段时，它允许您以微调的方式手动定义一个参数。这是当使用 Servlet 或者其他非 JAX-RS 环境时定义参数的唯一方法。

  此注解和 @ApiParam 注解一样都可以应用于方法参数上，不过 @ApiParam 更适用于参数不是包装类或者 String 的情况，此时配合 @ApiModel和@ApiModelProperty 再好不过，而 @ApiImplicitParam 通常适用于方法中有单个或多个参数且不是通过一个类去接收所有参数的情况，这时候使用它，非常合适。

源码

package io.swagger.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiImplicitParam {

    String name() default "";

    String value() default "";

    String defaultValue() default "";

    String allowableValues() default "";

    boolean required() default false;

    String access() default "";

    boolean allowMultiple() default false;

    String dataType() default "";

    Class<?> dataTypeClass() default Void.class;

    String paramType() default "";

    String example() default "";

    Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));

    String type() default "";

    String format() default "";

    boolean allowEmptyValue() default false;

    boolean readOnly() default false;

    String collectionFormat() default "";
}

从源码我们可以看到 @ApiImplicitParam 注解共有 17 个属性。不过这里面只有以下 2 个属性比较常用：

1、name (参数名称)

此属性表示参数的名称。为了保持适当的 Swagger 功能，当根据 parameType() (指参数类型) 命名参数时，请遵循以下规则：

(1)、如果参数类型是路径，其名称应当是路径中所关联的那部分 (相对路径)

(2)、对于所有的其他情况，其名称应当是当前应用程序希望接收的

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 打印消息
     *
     * @param msg 待打印的消息
     */
    @ApiOperation("打印消息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "msg"),
            @ApiImplicitParam(name = "author")
    })
    @GetMapping("/print")
    public R<String> printMsg(String msg, String author) {
        log.info("这是您发送的消息：{}", msg);
        return R.ok(msg);
    }
}

2、value (参数说明)

这是一个简短的参数描述。

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 展示方法
     */
    @ApiOperation("展示方法")
    @ApiImplicitParam(name = "request", value = "HTTP请求")
    @GetMapping("/show")
    public R<String> show(HttpServletRequest request) {
        String method = request.getMethod();
        return R.ok(method);
    }
}

3、allowableValues (参数范围)

限制此参数接收的值，以下有三种方法可以描述请求参数的范围：

(1)、设置一个值的列表，提供一个以逗号分割的列表。例如：first, second, third。

(2)、设置一个值的范围，以 “range” 开始这个值，周围用方括号表示最小值和最大值，或使用圆括号表示独占的最小值和最大值。例如：range[1, 5]、range(1, 5), range[1, 5)。注意，此属性需要配合 dataTypeClass 属性才有用，单独设置没有效果

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 获取随机数
     * @param seed 随机数种子
     */
    @ApiOperation("获取随机数")
    @ApiImplicitParam(name = "seed", value = "随机数种子", allowableValues = "1,2,3,4,5,6,7,8,9,10", dataTypeClass = Integer.class)
    @GetMapping("/random")
    public R<Integer> random(Integer seed) {
        Random random = new Random(seed);
        int i = random.nextInt();
        return R.ok(i);
    }

}

当使用swagger文档调用接口也可以看到：

4、required (参数是否必填)

指定参数为必要的还是非必要的，如果当前参数为path参数，应当设置此属性为true。

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 获取用户信息
     */
    @ApiOperation("获取用户信息")
    @ApiImplicitParam(name = "userId", value = "用户ID", required = true)
    @GetMapping("/info/{userId}")
    public R<Void> getUserInfo(@PathVariable("userId") Long userId) {
        return ok();
    }
}

说完了常用的属性，我们再来补充一下剩下的一些不常用属性：

@ApiImplicitParams

介绍

  此注解是 @ApiImplicitParam 注解的包装器，单独使用没有意义，必须和 @ApiImplicitParam 进行搭配，当接口方法中有一个及以上的参数时可以使用。

源码

package io.swagger.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiImplicitParams {

    ApiImplicitParam[] value();
}

从源码我们可以看到 @ApiImplicitParams 注解有且只有一个常用的属性：

1、value（注解列表）

一个用于API操作的 ApiImplicitParam 注解的列表

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 登录
     */
    @ApiOperation("登录")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", required = true),
            @ApiImplicitParam(name = "password", value = "密码", required = true)
    })
    @GetMapping("/login")
    public R<Void> login(String username, String password) {
        return ok();
    }
}

@ApiParam

介绍

  @ApiParam 注解作用在接口方法上面，以及接口方法中的参数位置的注解，其主要作用是用来给接口中的参数定义相关的参数说明，旨在帮助相关技术人员理解接口中每个参数的含义。注意，此注解只能在 JAX-RS 1.x/2.x 注解的组合中使用，和 @ApiImplicitParam 注解同样的是，都可以标注在方法上，对方法的参数进行解释说明。唯一的不同点是，@ApiImplicitParam 注解比 @ApiParam 更适合标注在包装类或 Spring 类上，且配合 @ApiImplicitParams 可以做到支持多个参数，而 @ApiParam 只能有一个。

源码

package io.swagger.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiParam {

    String name() default "";

    String value() default "";

    String defaultValue() default "";

    String allowableValues() default "";

    boolean required() default false;

    String access() default "";

    boolean allowMultiple() default false;

    boolean hidden() default false;

    String example() default "";

    Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));

    String type() default "";

    String format() default "";

    boolean allowEmptyValue() default false;

    boolean readOnly() default false;

    String collectionFormat() default "";
}

属性

从源码我们可以看到 @ApiParam 注解共有 15 个属性。不过这里面只有以下 2 个属性比较常用：

1、name（参数名称）

此属性代表了参数的名称，值可能来自字段、方法或参数名称，应当重写它。

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 打印消息
     * @param msg 消息
     */
    @ApiOperation("打印消息")
    @ApiParam(name = "msg")
    @GetMapping("/printMsg")
    public R<Void> printMsg(String msg) {
        System.out.println("msg = " + msg);
        return ok();
    }
}

2、value（参数说明）

这是一段简短的参数描述。

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 获取信息
     * @param msg 消息
     */
    @ApiOperation("获取信息")
    @ApiParam(name = "msg", value = "消息")
    @GetMapping("/getInfo")
    public R<String> getInfo(String msg) {
        String info = msg + "Hello,world";
        return ok(info);
    }

}

3、required (是否必填)

指定请求参数是否必填，假如当前参数类型为path则必须设置此属性。

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 获取信息
     * @param msg 消息
     */
    @ApiOperation("获取信息")
    @ApiParam(name = "msg", value = "消息", required = true)
    @GetMapping("/getInfo")
    public R<String> getInfo(String msg) {
        String info = msg + "Hello,world";
        return ok(info);
    }

}

说完了常用的属性，我们再来补充一下剩下的一些不常用属性：

Tips

  你知道吗？Spring 框架在控制器层面也提供了一些有关于请求参数的注解，通常swagger注解也会配合这些注解一起使用，了解这些注解对你百利而无一害。

注解	说明
@RequestParam	Spring的请求参数注解，可以标注在方法参数上，如果前后端参数不对应的话，可以使用此注解进行参数绑定
@RequestBody	将当前参数绑定为请求主体，POST、PUT方法中常用
@RequestHeader	如果方法需要接受请求头参数，那么可以使用此注解，表示当前参数是一个请求头参数
@RequestAttribute	将当前参数绑定为HTTP请求中的一个属性，通过 request.getAttribute() 方法可获取属性值
@RequestPart	可以将 “multipart/form-data” 请求的参数和方法参数进行相关联

实体层

@ApiModel

介绍

  为模型或视图对象提供额外的 swagger 说明信息， 被标注的类将会 “ 自我介绍 ”，因为它们在操作中被用作类型，不过程序员们更喜欢着眼于类的内部结构。此注解是作用在接口相关的实体类上的注解，用来对该接口的相关实体类添加额外的描述信息，一般和 @ApiModelProperty 注解配合使用。

源码

package io.swagger.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface ApiModel {

    String value() default "";

    String description() default "";

    Class<?> parent() default Void.class;

    String discriminator() default "";

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

    String reference() default "";
}

属性

从源码我们可以看到 @ApiModel 注解共有 6 个属性，不过这里面只有下面这1个属性比较常用：

1、value (模型描述)

为模型提供一个替代名称（替代类名），如果没有标注此属性，默认情况下使用类名。

实体层

/**
 * 用户对象
 *
 * @author 莪是男神
 */
@Data
@ApiModel("用户信息")
public class UserInfo implements Serializable {

    private static final long serialVersionUID = 1L;

    /** 用户ID */
    private Long userId;

    /** 部门ID */
    private Long deptId;

    /** 用户账号 */
    private String userName;

    /** 用户昵称 */
    private String nickName;

    /** 用户邮箱 */
    private String email;

    /** 手机号码 */
    private String phonenumber;

    /** 用户性别 */
    private String sex;

    /** 用户头像 */
    private String avatar;

    /** 密码 */
    private String password;

    /** 帐号状态（0正常 1停用） */
    private String status;

    /** 删除标志（0代表存在 2代表删除） */
    private String delFlag;

    /** 最后登录IP */
    private String loginIp;

    /** 最后登录时间 */
    private Date loginDate;

}

控制器层

/**
 * swagger注解学习
 *
 * @author 莪是男神
 * @date 2023/2/26 1:24
 */
@Api(tags = "swagger注解学习")
@Slf4j
@Anonymous
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {

    /**
     * 获取用户信息
     *
     * @param userId 用户ID
     */
    @ApiOperation("获取用户")
    @ApiImplicitParam(name = "userId", value = "用户ID", dataTypeClass = Long.class, paramType = "query", required = true)
    @GetMapping("/info")
    public R<UserInfo> getInfo(Long userId) {
        UserInfo userInfo = new UserInfo();
        userInfo.setUserId(userId);
        return R.ok(userInfo);
    }

}

说完了常用的属性，我们再来补充一下剩下的一些不常用属性：

@ApiModelProperty

介绍

  此注解可标注在方法或字段上，通常配合 @ApiModel 注解一起使用，用于添加或操作接口相关实体类的字段信息

源码

package io.swagger.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiModelProperty {
 
    String value() default "";

    String name() default "";

    String allowableValues() default "";

    String access() default "";

    String notes() default "";

    String dataType() default "";

    boolean required() default false;

    int position() default 0;

    boolean hidden() default false;

    String example() default "";

    @Deprecated
    boolean readOnly() default false;

    AccessMode accessMode() default AccessMode.AUTO;

    String reference() default "";

    boolean allowEmptyValue() default false;

    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));

    enum AccessMode {
        AUTO,
        READ_ONLY,
        READ_WRITE;
    }
}

属性

  从源码我们可以看到 @ApiModelProperty 注解除了已废弃的1个，共有 14 个属性和一个枚举，不过这里面只有下面这1个属性比较常用：

1、value (字段描述)

一段简短的字段描述。

/**
 * 用户对象
 *
 * @author 莪是男神
 */
@Data
@ApiModel(value = "用户信息")
public class UserInfo {

    private static final long serialVersionUID = 1L;

    /** 用户ID */
    @ApiModelProperty("用户ID")
    private Long userId;

    /** 部门ID */
    @ApiModelProperty("部门ID")
    private Long deptId;

    /** 用户账号 */
    @ApiModelProperty("用户账号")
    private String userName;

    /** 用户昵称 */
    @ApiModelProperty("用户昵称")
    private String nickName;

    /** 用户邮箱 */
    @ApiModelProperty("用户邮箱")
    private String email;

    /** 手机号码 */
    @ApiModelProperty("手机号码")
    private String phonenumber;

    /** 用户性别 */
    @ApiModelProperty("用户性别")
    private String sex;

    /** 用户头像 */
    @ApiModelProperty("用户头像")
    private String avatar;

    /** 密码 */
    @ApiModelProperty("密码")
    private String password;

    /** 帐号状态（0正常 1停用） */
    @ApiModelProperty("帐号状态（0正常 1停用）")
    private String status;

    /** 删除标志（0代表存在 2代表删除） */
    @ApiModelProperty("删除标志（0代表存在 2代表删除）")
    private String delFlag;

    /** 最后登录IP */
    @ApiModelProperty("最后登录IP")
    private String loginIp;

    /** 最后登录时间 */
    @ApiModelProperty("最后登录时间")
    private Date loginDate;

}

说完了常用的属性，我们再来补充一下剩下的一些不常用属性：