思淘网站建设,电商网页的特点,建站网站知乎,网站优化方案和实施常用Swagger注解汇总 前言 在实际编写后端代码的过程中#xff0c;我们可能经常使用到 swagger 注解#xff0c;但是会用不代表了解#xff0c;你知道每个注解都有什么属性吗#xff1f;你都用过这些属性吗#xff1f;了解它们的作用吗#xff1f;本文在此带大家总结一下…常用Swagger注解汇总 前言 在实际编写后端代码的过程中我们可能经常使用到 swagger 注解但是会用不代表了解你知道每个注解都有什么属性吗你都用过这些属性吗了解它们的作用吗本文在此带大家总结一下常用的swagger注解供大家学习理解。 文章目录常用Swagger注解汇总控制器层ApiApiOperationApiImplicitParamApiImplicitParamsApiParam实体层ApiModelApiModelProperty控制器层 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 RVoid testApi(){System.out.println(Hello,world);return ok();}
}说完了常用的属性我们再来补充一下剩下的一些不常用属性
属性数据类型默认值作用示例说明valueString“”接口分组说明在实际开发中并不常用且值会被 tags 属性覆盖Api(value “操作名称”) 或 Api(“操作名称”)隐式地设置操作标签 (即操作名称)旧版本支持 (阅读描述)。在 Swagger 核心 1.3.X 的版本中此属性仅作为主机 API 资源的声明路径到 1.5.X 版本之后就不再关联了。hiddenbooleanfalse隐藏该分组下的所有接口。此外要注意的是接口的显示隐藏应该根据特定的安全策略和特定客户需求来确定Api(hidden true)隐藏资源下的操作。此属性的值默认为 false当设置为 true 时该分组的所有操作都会在 swagger 文档中被隐藏适用于接口暂时不需要使用时的情况。producesString“”指定的content-type 的输出Api(produces“application/json”) 此属性在新版本的 swagger 中已不再使用仅用于向下兼容旧版本。对应此资源下操作生成的字段。获取逗号分割的内容类型值例如“application/json”“application/xml” 将会提醒操作生成 JSON 或 XML 输出。对于 JAX-RS 资源如果存在将会自动获取 Produces 注解的值同时也可用于覆盖 Swapper 文档的 Produces 的值。consumesString“”指定的content-type 的输入Api(consumes“application/xml”)对应此资源下操作消费的字段。获取逗号分割的内容类型值。例如例如“application/json”“application/xml” 将会提醒操作接收 JSON 或 XML 输入。对于 JAX-RS 资源如果存在将会自动获取 Consumes 注解的值同时也可用于覆盖 Swagger 文档的 Consumes 的值。protocolsString“”网络请求协议Api(protocols “http,https”)设置此资源下操作的指定协议(或方案)。以逗号分割可用的协议值可用值http, https, ws, wssauthorizationsAuthorization[]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 RInteger 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 RInteger getInfo() {int i 1;return R.ok(i);}
}说完了常用的属性我们再来补充一下剩下的一些不常用属性
属性数据类型默认值作用示例说明tagsString[]“”定义接口分组如果一个接口涉及到多个业务场景那这个时候需要我们对接口进行多个分组ApiOperation(tags{“测试标签1”, “测试标签2”})一个用于控制 API 文档标签的列表标签可按资源或者其他标识符对操作进行分组。此外操作的 Api 注解的 value 或者 tags 属性将会覆盖其单个的非空值。responseClass?Void.class指定响应的数据类型ApiOperation(response ReturnResult.class)操作返回的响应类型在 JAX-RS 应用程序中方法的返回类型将会自动使用除了 javax.ws.core.Response。而在其他情况下操作返回类型默认为 void 因为不知道实际的响应类型。设置此属性将会覆盖任何自动派生的数据类型如果被用到的值是用一个类 (Integer、Long) 的基本数据类型表示的那么则会使用相应的基本数据类型响应responseContainerString“”包装HTTP响应的容器类型ApiOperation(responseContainer “List”)声明一个包装响应的容器有效值只有 “List”、“Set”、“Map”其他值都会被忽略。responseReferenceString“”支持远程调用的响应数据类型比 response 属性优先级更高ApiOperation(responseReference “java.lang.Integer”)指定一个响应类型的引用。此引用可以是本地的或者远程的并且将按原样使用覆任何的指定的 response 属性类httpMethodString“”接口使用的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”。nicknameString“”接口别名方便前后端沟通使用没有其他含义ApiOperation(nickname “测试别名”)对应操作 ID 字段。此操作 ID 被用于第三方工具唯一识别此操作的手段在 Swagger 2.0 中这不是必填参数如果不提供值可以为空。producesString“”指定的content-type 的输出ApiOperation(produces“application/json”)对应此资源下操作生成的字段。获取逗号分割的内容类型值例如“application/json”“application/xml” 将会提醒操作生成 JSON 或 XML 输出。对于 JAX-RS 资源如果存在将会自动获取 Produces 注解的值同时也可用于覆盖 Swapper 文档的 Produces 的值。consumesString“”指定的content-type 的输入ApiOperation(consumes“application/xml”)对应此资源下操作消费的字段。获取逗号分割的内容类型值。例如例如“application/json”“application/xml” 将会提醒操作接收 JSON 或 XML 输入。对于 JAX-RS 资源如果存在将会自动获取 Consumes 注解的值同时也可用于覆盖 Swagger 文档的 Consumes 的值。protocolsString“”网络请求协议ApiOperation(protocols “http,https”)设置此资源下操作的指定协议(或方案)。以逗号分割可用的协议值可用值http, https, ws, wssauthorizationsAuthorization[]Authorization(value “”)定义接口的授权方案对应操作对象的安全字段。获取此资源下操作的授权 (安全需求) 列表这可能会被特定的操作覆盖。hiddenbooleanfalse此属性用于隐藏接口但要注意的是接口的显示隐藏应该根据特定的安全策略和特定客户需求来ApiOperation(hidden true)操作列表中隐藏此操作responseHeadersResponseHeader[]ResponseHeader(name “”, response Void.class)HTTP响应头参数ApiOperation(responseHeaders {ResponseHeader(name “auth”, response String.class)})在响应中可能提供的响应头列表codeint200HTTP状态码swagger自动生成一般不用设置ApiOperation(code 404)HTTP 响应状态码其值应该是正式 HTTP 状态码定义的其中之一extensionsExtension[]Extension(properties ExtensionProperty(name “”, value “”))可选的扩展属性数组ApiOperation(extensions Extension(properties ExtensionProperty(name “key”, value “value”)))可选的扩展属性数组ignoreJsonViewbooleanfalse忽略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 RString 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 RString 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 RInteger 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 RVoid getUserInfo(PathVariable(userId) Long userId) {return ok();}
}说完了常用的属性我们再来补充一下剩下的一些不常用属性
属性数据类型默认值概述示例说明defaultValueString“”参数默认值ApiImplicitParam(defaultValue “1”)描述参数的默认值当请求参数中有分页参数或有需要设置默认值的参数可设置此属性accessString“”允许API文档过滤参数更多细节请查看 SwaggerSpecFilter 类allowMultipleString“”此参数是否能接受多个值ApiImplicitParam(allowMultiple true)指定此参数是否能在各种情况下能够接收多个值默认值为falsedataTypeString“”数据类型ApiImplicitParam(dataType“int”)参数的数据类型可以是类名或者基本数据类型dataTypeClassClass?Void.classclass 类型此属性不定义的话程序可能会有警告ApiImplicitParam(dataTypeClass String.class)参数的 class 类型如果此属性指定了值的话会覆盖 dataType 提供的paramTypeString“”参数的HTTP参数类型ApiImplicitParam(param“query”)参数的参数类型有效值是 path、query、body、header 或者 form其他值会被忽略exampleString“”参数示例ApiImplicitParam(example“1”)一个非 body 类型的单独参数示例examplesExampleExample(value ExampleProperty(mediaType “”, value “”))参数示例集合参数示例仅适用于body参数typeString“”参数类型ApiImplicitParam(type “int”)添加了覆盖所检测到的类型的能力formatString“”参数的自定义格式ApiImplicitParam(type “integer”, format“int64”)添加了提供自定义格式的能力allowEmptyValuebooleanfalse是否允许传递空值ApiImplicitParam(allowEmptyValuetrue)添加了设置空值格式的能力readOnlybooleanfalse是否只读ApiImplicitParam(readOnlytrue)添加了被认定为只读的能力collectionFormatString“”集合的格式添加了使用数组类型覆盖集合格式的能力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 RVoid 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 RVoid 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 RString 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 RString getInfo(String msg) {String info msg Hello,world;return ok(info);}}说完了常用的属性我们再来补充一下剩下的一些不常用属性
属性数据类型默认值概述示例说明defaultValueString“”参数的默认值ApiParam(defaultValue “1”)描述参数的默认值当请求参数中有分页参数或有需要设置默认值的参数可设置此属性accessString“”允许API文档过滤参数更多细节请查看 SwaggerSpecFilter 类allowMultiplebooleanfalse此参数是否能接受多个值ApiParam(allowMultiple true)指定此参数是否能在各种情况下能够接收多个值默认值为falsehiddenbooleanfalse控制参数的隐藏或显示ApiParam(hidden true)隐藏参数列表中的此参数exampleString“”参数示例ApiParam(example“1”)一个非 body 类型的单独参数示例examplesExampleExample(value ExampleProperty(mediaType “”, value “”))参数示例集合参数示例仅适用于body参数typeString“”参数类型ApiParam(type “int”)添加了覆盖所检测到的类型的能力formatString“”参数格式ApiParam(type “integer”, format“int64”)添加了提供自定义格式的能力allowEmptyValuebooleanfalse是否允许传递空值ApiParam(allowEmptyValuetrue)添加了设置空值格式的能力readOnlybooleanfalse是否只读ApiParam(readOnlytrue)添加了被认定为只读的能力collectionFormatString“”集合的格式添加了使用数组类型覆盖集合格式的能力Tips 你知道吗Spring 框架在控制器层面也提供了一些有关于请求参数的注解通常swagger注解也会配合这些注解一起使用了解这些注解对你百利而无一害。 注解说明RequestParamSpring的请求参数注解可以标注在方法参数上如果前后端参数不对应的话可以使用此注解进行参数绑定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 RUserInfo getInfo(Long userId) {UserInfo userInfo new UserInfo();userInfo.setUserId(userId);return R.ok(userInfo);}}说完了常用的属性我们再来补充一下剩下的一些不常用属性
属性数据类型默认值概述示例说明descriptionString“”类描述。在实际开发中此属性一般会配合 value 属性进行使用很少会出现只是用 value 属性而不使用 description 属性的情况。ApiMode(description “系统用户的详细信息”)为此模型提供一个冗长的描述parentClass?Void.class描述类的继承关系ApiModel(parent Object.class)为模型提供一个父类允许描述其中的继承关系discriminatorString“”实现类的多态性ApiModel(discriminator “userId”)此属性用于支持模型继承以及多态性。其值用作鉴别器的字段名称基于这个字段可以断言需要使用哪种子类型subTypesClass?[]{}展示继承接口相关实体类class的子类ApiModel(subTypes{String.class})一个继承此模型的子类数组referenceString“”实体类的类型引用指定对应类型定义的引用并覆盖所指定的任何其他的元数据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 ;Deprecatedboolean 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;}说完了常用的属性我们再来补充一下剩下的一些不常用属性
属性数据类型默认值概述示例说明nameString“”字段的名称ApiModelProperty(name “userId”)允许覆盖属性的名称defaultValueString“”字段的默认值ApiModelProperty(defaultValue “1”)描述属性的默认值当属性需要设置默认值时可设置此属性accessString“”允许API文档过滤参数更多细节请查看 SwaggerSpecFilter 类notesString“”暂时没用ApiModelProperty(notes “暂时没用”)注解的扩展属性当前未使用。dataTypeString“”描述字段的数据类型ApiModelProperty(dataType“int”)这个属性描述字段的数据类型其值可以是对象或者是基本数据类型而且会覆盖从类属性中读取的数据类型。requiredbooleanfalse是否必填ApiModelProperty(requiredtrue)指定字段为必要的还是非必要的positionint0指定字段在swagger文档中的显示顺序ApiModelProperty(position 1)允许排序类的字段hiddenbooleanfalse隐藏类的字段ApiModelProperty(hidden true)允许类的字段在swagger模型定义中隐藏exampleString“”字段的示例值ApiModelProperty(example “1”)该字段的一个示例值accessModeAccessModedefault AccessMode.AUTO字段的访问模式ApiModelProperty(accessModeREAD_ONLY)允许指定字段的访问模式 (AccessMode.READ_ONLY, READ_WRITE)referenceString“”字段的类型引用指定对应类型定义的引用并覆盖所指定的任何其他的元数据allowEmptyValuebooleanfalse是否允许传递的字段为空值ApiModelProperty(allowEmptyValuetrue)允许传递空值extensionsExtension[]Extension(properties ExtensionProperty(name “”, value “”))该注解的扩展属性数组可用于第三方ApiModelProperty(Extension(properties ExtensionProperty(name “size”, value “1”))返回可选的扩展属性数组
