常用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();
}
}
说完了常用的属性，我们再来补充一下剩下的一些不常用属性：
| 属性 | 数据类型 | 默认值 | 作用 | 示例 | 说明 |
|---|---|---|---|---|---|
| value | String | “” | 接口分组说明，在实际开发中并不常用，且值会被 tags 属性覆盖 | @Api(value = “操作名称”) 或 @Api(“操作名称”) | 隐式地设置操作标签 (即操作名称)，旧版本支持 (阅读描述)。 在 Swagger 核心 1.3.X 的版本中，此属性仅作为主机 API 资源的声明路径，到 1.5.X 版本之后就不再关联了。 |
| hidden | boolean | false | 隐藏该分组下的所有接口。此外要注意的是，接口的显示隐藏应该根据特定的安全策略和特定客户需求来确定 | @Api(hidden = true) | 隐藏资源下的操作。此属性的值默认为 false，当设置为 true 时，该分组的所有操作都会在 swagger 文档中被隐藏，适用于接口暂时不需要使用时的情况。 |
| produces | String | “” | 指定的content-type 的输出 | @Api(produces=“application/json”) | 此属性在新版本的 swagger 中已不再使用，仅用于向下兼容旧版本。对应此资源下操作生成的字段。 获取逗号分割的内容类型值，例如，“application/json”，“application/xml” 将会提醒操作生成 JSON 或 XML 输出。 对于 JAX-RS 资源，如果存在将会自动获取 @Produces 注解的值，同时也可用于覆盖 Swapper 文档的 @Produces 的值。 |
| consumes | String | “” | 指定的content-type 的输入 | @Api(consumes=“application/xml”) | 对应此资源下操作消费的字段。 获取逗号分割的内容类型值。例如例如，“application/json”，“application/xml” 将会提醒操作接收 JSON 或 XML 输入。 对于 JAX-RS 资源，如果存在将会自动获取 @Consumes 注解的值，同时也可用于覆盖 Swagger 文档的 @Consumes 的值。 |
| protocols | String | “” | 网络请求协议 | @Api(protocols = “http,https”) | 设置此资源下操作的指定协议(或方案)。 以逗号分割可用的协议值，可用值：http, https, ws, wss |
| authorizations | Authorization[] | @Authorization(value = “”) | 规定接口分组的授权方案 | 对应操作对象的安全字段。 获取此资源下操作的授权 (安全需求) 列表，这可能会被特定的操作覆盖。 |
@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);
}
}
说完了常用的属性，我们再来补充一下剩下的一些不常用属性：
| 属性 | 数据类型 | 默认值 | 作用 | 示例 | 说明 |
|---|---|---|---|---|---|
| tags | String[] | “” | 定义接口分组，如果一个接口涉及到多个业务场景，那这个时候需要我们对接口进行多个分组 | @ApiOperation(tags={“测试标签1”, “测试标签2”}) | 一个用于控制 API 文档标签的列表，标签可按资源或者其他标识符对操作进行分组。此外，操作的 Api 注解的 value 或者 tags 属性将会覆盖其单个的非空值。 |
| response | Class<?> | Void.class | 指定响应的数据类型 | @ApiOperation(response = ReturnResult.class) | 操作返回的响应类型 在 JAX-RS 应用程序中，方法的返回类型将会自动使用，除了 javax.ws.core.Response。而在其他情况下，操作返回类型默认为 void ，因为不知道实际的响应类型。设置此属性将会覆盖任何自动派生的数据类型 如果被用到的值是用一个类 (Integer、Long) 的基本数据类型表示的，那么则会使用相应的基本数据类型响应 |
| responseContainer | String | “” | 包装HTTP响应的容器类型 | @ApiOperation(responseContainer= “List”) | 声明一个包装响应的容器，有效值只有 “List”、“Set”、“Map”，其他值都会被忽略。 |
| responseReference | String | “” | 支持远程调用的响应数据类型，比 response 属性优先级更高 | @ApiOperation(responseReference= “java.lang.Integer”) | 指定一个响应类型的引用。此引用可以是本地的或者远程的并且将按原样使用，覆任何的指定的 response 属性类 |
| httpMethod | String | “” | 接口使用的HTTP方法 | @ApiOperation(httpMethod= “GET”) | 对应使用的HTTP方法 如果是无状态的，在 JAX-RS 应用程序中，下列 JAX-RS 注解将会被扫描且使用：@GET、@HEAD、@POST、@PUT、@DELETE 和 @OPTIONS。注意即使它不是 JAX-RS规范指定的部分（也可以被扫描并使用），如果您创建并使用 @PATCH 注解，它也会被解析并使用，如果设置了此属性，那么将会覆盖 JAX-RS 注解。 对于 Sevlet 而言，您必须手动指定 HTTP 方法，可接收的值是 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“GET”、“DELETE” 和 “PATCH”。 |
| nickname | String | “” | 接口别名，方便前后端沟通使用，没有其他含义 | @ApiOperation(nickname= “测试别名”) | 对应操作 ID 字段。 此操作 ID 被用于第三方工具唯一识别此操作的手段，在 Swagger 2.0 中，这不是必填参数，如果不提供值可以为空。 |
| produces | String | “” | 指定的content-type 的输出 | @ApiOperation(produces=“application/json”) | 对应此资源下操作生成的字段。 获取逗号分割的内容类型值，例如，“application/json”，“application/xml” 将会提醒操作生成 JSON 或 XML 输出。 对于 JAX-RS 资源，如果存在将会自动获取 @Produces 注解的值，同时也可用于覆盖 Swapper 文档的 @Produces 的值。 |
| consumes | String | “” | 指定的content-type 的输入 | @ApiOperation(consumes=“application/xml”) | 对应此资源下操作消费的字段。 获取逗号分割的内容类型值。例如例如，“application/json”，“application/xml” 将会提醒操作接收 JSON 或 XML 输入。 对于 JAX-RS 资源，如果存在将会自动获取 @Consumes 注解的值，同时也可用于覆盖 Swagger 文档的 @Consumes 的值。 |
| protocols | String | “” | 网络请求协议 | @ApiOperation(protocols = “http,https”) | 设置此资源下操作的指定协议(或方案)。 以逗号分割可用的协议值，可用值：http, https, ws, wss |
| authorizations | Authorization[] | @Authorization(value = “”) | 定义接口的授权方案 | 对应操作对象的安全字段。 获取此资源下操作的授权 (安全需求) 列表，这可能会被特定的操作覆盖。 |
|
| hidden | boolean | false | 此属性用于隐藏接口，但要注意的是，接口的显示隐藏应该根据特定的安全策略和特定客户需求来 | @ApiOperation(hidden= true) | 操作列表中隐藏此操作 |
| responseHeaders | ResponseHeader[] | @ResponseHeader(name = “”, response = Void.class) | HTTP响应头参数 | @ApiOperation(responseHeaders = {@ResponseHeader(name = “auth”, response = String.class)}) | 在响应中可能提供的响应头列表 |
| code | int | 200 | HTTP状态码，swagger自动生成，一般不用设置 | @ApiOperation(code = 404) | HTTP 响应状态码，其值应该是正式 HTTP 状态码定义的其中之一 |
| extensions | Extension[] | @Extension(properties = @ExtensionProperty(name = “”, value = “”)) | 可选的扩展属性数组 | @ApiOperation(extensions = @Extension(properties = @ExtensionProperty(name = “key”, value = “value”))) | 可选的扩展属性数组 |
| ignoreJsonView | boolean | false | 忽略JsonView 注解 | @ApiOperation(ignoreJsonView = true) | 当解析操作和类型时忽略 @JsonView 注解，用于向后兼容 |
@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();
}
}
说完了常用的属性，我们再来补充一下剩下的一些不常用属性：
| 属性 | 数据类型 | 默认值 | 概述 | 示例 | 说明 |
|---|---|---|---|---|---|
| defaultValue | String | “” | 参数默认值 | @ApiImplicitParam(defaultValue = “1”) | 描述参数的默认值，当请求参数中有分页参数或有需要设置默认值的参数，可设置此属性 |
| access | String | “” | 允许API文档过滤参数，更多细节请查看 SwaggerSpecFilter 类 | ||
| allowMultiple | String | “” | 此参数是否能接受多个值 | @ApiImplicitParam(allowMultiple= true) | 指定此参数是否能在各种情况下能够接收多个值，默认值为false |
| dataType | String | “” | 数据类型 | @ApiImplicitParam(dataType=“int”) | 参数的数据类型，可以是类名或者基本数据类型 |
| dataTypeClass | Class<?> | Void.class | class 类型，此属性不定义的话程序可能会有警告 | @ApiImplicitParam(dataTypeClass = String.class) | 参数的 class 类型，如果此属性指定了值的话会覆盖 dataType 提供的 |
| paramType | String | “” | 参数的HTTP参数类型 | @ApiImplicitParam(param=“query”) | 参数的参数类型，有效值是 path、query、body、header 或者 form，其他值会被忽略 |
| example | String | “” | 参数示例 | @ApiImplicitParam(example=“1”) | 一个非 body 类型的单独参数示例 |
| examples | Example | @Example(value = @ExampleProperty(mediaType = “”, value = “”)) | 参数示例集合 | 参数示例，仅适用于body参数 | |
| type | String | “” | 参数类型 | @ApiImplicitParam(type = “int”) | 添加了覆盖所检测到的类型的能力 |
| format | String | “” | 参数的自定义格式 | @ApiImplicitParam(type = “integer”, format=“int64”) | 添加了提供自定义格式的能力 |
| allowEmptyValue | boolean | false | 是否允许传递空值 | @ApiImplicitParam(allowEmptyValue=true) | 添加了设置空值格式的能力 |
| readOnly | boolean | false | 是否只读 | @ApiImplicitParam(readOnly=true) | 添加了被认定为只读的能力 |
| collectionFormat | String | “” | 集合的格式 | 添加了使用数组类型覆盖集合格式的能力 |
@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);
}
}
说完了常用的属性，我们再来补充一下剩下的一些不常用属性：
| 属性 | 数据类型 | 默认值 | 概述 | 示例 | 说明 |
|---|---|---|---|---|---|
| defaultValue | String | “” | 参数的默认值 | @ApiParam(defaultValue = “1”) | 描述参数的默认值，当请求参数中有分页参数或有需要设置默认值的参数，可设置此属性 |
| access | String | “” | 允许API文档过滤参数，更多细节请查看 SwaggerSpecFilter 类 | ||
| allowMultiple | boolean | false | 此参数是否能接受多个值 | @ApiParam(allowMultiple= true) | 指定此参数是否能在各种情况下能够接收多个值，默认值为false |
| hidden | boolean | false | 控制参数的隐藏或显示 | @ApiParam(hidden = true) | 隐藏参数列表中的此参数 |
| example | String | “” | 参数示例 | @ApiParam(example=“1”) | 一个非 body 类型的单独参数示例 |
| examples | Example | @Example(value = @ExampleProperty(mediaType = “”, value = “”)) | 参数示例集合 | 参数示例，仅适用于body参数 | |
| type | String | “” | 参数类型 | @ApiParam(type = “int”) | 添加了覆盖所检测到的类型的能力 |
| format | String | “” | 参数格式 | @ApiParam(type = “integer”, format=“int64”) | 添加了提供自定义格式的能力 |
| allowEmptyValue | boolean | false | 是否允许传递空值 | @ApiParam(allowEmptyValue=true) | 添加了设置空值格式的能力 |
| readOnly | boolean | false | 是否只读 | @ApiParam(readOnly=true) | 添加了被认定为只读的能力 |
| collectionFormat | String | “” | 集合的格式 | 添加了使用数组类型覆盖集合格式的能力 |
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);
}
}
说完了常用的属性，我们再来补充一下剩下的一些不常用属性：
| 属性 | 数据类型 | 默认值 | 概述 | 示例 | 说明 |
|---|---|---|---|---|---|
| description | String | “” | 类描述。 在实际开发中，此属性一般会配合 value 属性进行使用，很少会出现只是用 value 属性而不使用 description 属性的情况。 |
@ApiMode(description = “系统用户的详细信息”) | 为此模型提供一个冗长的描述 |
| parent | Class<?> | Void.class | 描述类的继承关系 | @ApiModel(parent = Object.class) | 为模型提供一个父类，允许描述其中的继承关系 |
| discriminator | String | “” | 实现类的多态性 | @ApiModel(discriminator= “userId”) | 此属性用于支持模型继承以及多态性。 其值用作鉴别器的字段名称，基于这个字段，可以断言需要使用哪种子类型 |
| subTypes | Class<?>[] | {} | 展示继承接口相关实体类class的子类 | @ApiModel(subTypes={String.class}) | 一个继承此模型的子类数组 |
| reference | String | “” | 实体类的类型引用 | 指定对应类型定义的引用，并覆盖所指定的任何其他的元数据 |
@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;
}
说完了常用的属性，我们再来补充一下剩下的一些不常用属性：
| 属性 | 数据类型 | 默认值 | 概述 | 示例 | 说明 |
|---|---|---|---|---|---|
| name | String | “” | 字段的名称 | @ApiModelProperty(name = “userId”) | 允许覆盖属性的名称 |
| defaultValue | String | “” | 字段的默认值 | @ApiModelProperty(defaultValue = “1”) | 描述属性的默认值，当属性需要设置默认值时，可设置此属性 |
| access | String | “” | 允许API文档过滤参数，更多细节请查看 SwaggerSpecFilter 类 | ||
| notes | String | “” | 暂时没用 | @ApiModelProperty(notes= “暂时没用”) | 注解的扩展属性，当前未使用。 |
| dataType | String | “” | 描述字段的数据类型 | @ApiModelProperty(dataType=“int”) | 这个属性描述字段的数据类型，其值可以是对象或者是基本数据类型，而且会覆盖从类属性中读取的数据类型。 |
| required | boolean | false | 是否必填 | @ApiModelProperty(required=true) | 指定字段为必要的还是非必要的 |
| position | int | 0 | 指定字段在swagger文档中的显示顺序 | @ApiModelProperty(position= 1) | 允许排序类的字段 |
| hidden | boolean | false | 隐藏类的字段 | @ApiModelProperty(hidden = true) | 允许类的字段在swagger模型定义中隐藏 |
| example | String | “” | 字段的示例值 | @ApiModelProperty(example= “1”) | 该字段的一个示例值 |
| accessMode | AccessMode | default AccessMode.AUTO | 字段的访问模式 | @ApiModelProperty(accessMode=READ_ONLY) | 允许指定字段的访问模式 (AccessMode.READ_ONLY, READ_WRITE) |
| reference | String | “” | 字段的类型引用 | 指定对应类型定义的引用，并覆盖所指定的任何其他的元数据 | |
| allowEmptyValue | boolean | false | 是否允许传递的字段为空值 | @ApiModelProperty(allowEmptyValue=true) | 允许传递空值 |
| extensions | Extension[] | @Extension(properties = @ExtensionProperty(name = “”, value = “”)) | 该注解的扩展属性数组，可用于第三方 | @ApiModelProperty(@Extension(properties = @ExtensionProperty(name = “size”, value = “1”)) | 返回可选的扩展属性数组 |