常用Swagger注解汇总

news2024/11/26 18:26:02

常用Swagger注解汇总

前言

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

文章目录

  • 常用Swagger注解汇总
  • 控制器层
    • @Api
    • @ApiOperation
    • @ApiImplicitParam
    • @ApiImplicitParams
    • @ApiParam
  • 实体层
    • @ApiModel
    • @ApiModelProperty

控制器层

 

@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();
    }
}

@Api注解的tags属性

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

属性数据类型默认值作用示例说明
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, wss
authorizationsAuthorization[]@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);
    }
}

@ApiOperation注解的value属性

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);
    }
}

@ApiOperation注解的notes属性

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

属性数据类型默认值作用示例说明
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, wss
authorizationsAuthorization[]@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 R<String> printMsg(String msg, String author) {
        log.info("这是您发送的消息：{}", msg);
        return R.ok(msg);
    }
}

@ApiImplicitParam注解的name属性

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);
    }
}

@ApiImplicitParam注解的value属性

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);
    }

}

@ApiImplicitParam注解的allowableValues属性01

当使用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();
    }
}

@ApiImplicitParam注解的required属性

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

属性数据类型默认值概述示例说明
defaultValueString“”参数默认值@ApiImplicitParam(defaultValue = “1”)描述参数的默认值，当请求参数中有分页参数或有需要设置默认值的参数，可设置此属性
accessString“”允许API文档过滤参数，更多细节请查看 SwaggerSpecFilter 类
allowMultipleString“”此参数是否能接受多个值@ApiImplicitParam(allowMultiple= true)指定此参数是否能在各种情况下能够接收多个值，默认值为false
dataTypeString“”数据类型@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 类型的单独参数示例
examplesExample@Example(value = @ExampleProperty(mediaType = “”, value = “”))参数示例集合参数示例，仅适用于body参数
typeString“”参数类型@ApiImplicitParam(type = “int”)添加了覆盖所检测到的类型的能力
formatString“”参数的自定义格式@ApiImplicitParam(type = “integer”, format=“int64”)添加了提供自定义格式的能力
allowEmptyValuebooleanfalse是否允许传递空值@ApiImplicitParam(allowEmptyValue=true)添加了设置空值格式的能力
readOnlybooleanfalse是否只读@ApiImplicitParam(readOnly=true)添加了被认定为只读的能力
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 R<Void> login(String username, String password) {
        return ok();
    }
}

@ApiImplicitParams注解的value属性

@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();
    }
}

@ApiParam注解的name属性

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);
    }

}

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

属性数据类型默认值概述示例说明
defaultValueString“”参数的默认值@ApiParam(defaultValue = “1”)描述参数的默认值，当请求参数中有分页参数或有需要设置默认值的参数，可设置此属性
accessString“”允许API文档过滤参数，更多细节请查看 SwaggerSpecFilter 类
allowMultiplebooleanfalse此参数是否能接受多个值@ApiParam(allowMultiple= true)指定此参数是否能在各种情况下能够接收多个值，默认值为false
hiddenbooleanfalse控制参数的隐藏或显示@ApiParam(hidden = true)隐藏参数列表中的此参数
exampleString“”参数示例@ApiParam(example=“1”)一个非 body 类型的单独参数示例
examplesExample@Example(value = @ExampleProperty(mediaType = “”, value = “”))参数示例集合参数示例，仅适用于body参数
typeString“”参数类型@ApiParam(type = “int”)添加了覆盖所检测到的类型的能力
formatString“”参数格式@ApiParam(type = “integer”, format=“int64”)添加了提供自定义格式的能力
allowEmptyValuebooleanfalse是否允许传递空值@ApiParam(allowEmptyValue=true)添加了设置空值格式的能力
readOnlybooleanfalse是否只读@ApiParam(readOnly=true)添加了被认定为只读的能力
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 R<UserInfo> 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 "";

    @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;

}

@ApiModelProperty注解的value属性

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

属性数据类型默认值概述示例说明
nameString“”字段的名称@ApiModelProperty(name = “userId”)允许覆盖属性的名称
defaultValueString“”字段的默认值@ApiModelProperty(defaultValue = “1”)描述属性的默认值，当属性需要设置默认值时，可设置此属性
accessString“”允许API文档过滤参数，更多细节请查看 SwaggerSpecFilter 类
notesString“”暂时没用@ApiModelProperty(notes= “暂时没用”)注解的扩展属性，当前未使用。
dataTypeString“”描述字段的数据类型@ApiModelProperty(dataType=“int”)这个属性描述字段的数据类型，其值可以是对象或者是基本数据类型，而且会覆盖从类属性中读取的数据类型。
requiredbooleanfalse是否必填@ApiModelProperty(required=true)指定字段为必要的还是非必要的
positionint0指定字段在swagger文档中的显示顺序@ApiModelProperty(position= 1)允许排序类的字段
hiddenbooleanfalse隐藏类的字段@ApiModelProperty(hidden = true)允许类的字段在swagger模型定义中隐藏
exampleString“”字段的示例值@ApiModelProperty(example= “1”)该字段的一个示例值
accessModeAccessModedefault AccessMode.AUTO字段的访问模式@ApiModelProperty(accessMode=READ_ONLY)允许指定字段的访问模式 (AccessMode.READ_ONLY, READ_WRITE)
referenceString“”字段的类型引用指定对应类型定义的引用，并覆盖所指定的任何其他的元数据
allowEmptyValuebooleanfalse是否允许传递的字段为空值@ApiModelProperty(allowEmptyValue=true)允许传递空值
extensionsExtension[]@Extension(properties = @ExtensionProperty(name = “”, value = “”))该注解的扩展属性数组，可用于第三方@ApiModelProperty(@Extension(properties = @ExtensionProperty(name = “size”, value = “1”))返回可选的扩展属性数组

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/384689.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

6-2 SpringCloud快速开发入门:声明式服务消费 Feign实现消费者

6-2 SpringCloud快速开发入门:声明式服务消费 Feign实现消费者

声明式服务消费 Feign实现消费者 使用 Feign实现消费者&#xff0c;我们通过下面步骤进行&#xff1a; 第一步&#xff1a;创建普通 Spring Boot工程 第二步&#xff1a;添加依赖 <dependencies><!--SpringCloud 集成 eureka 客户端的起步依赖--><dependency>…
阅读更多...
图解LeetCode——剑指 Offer 34. 二叉树中和为某一值的路径

图解LeetCode——剑指 Offer 34. 二叉树中和为某一值的路径

一、题目 给你二叉树的根节点 root 和一个整数目标和 targetSum &#xff0c;找出所有 从根节点到叶子节点 路径总和等于给定目标和的路径。叶子节点 是指没有子节点的节点。 二、示例 2.1> 示例 1&#xff1a; 【输入】root [5,4,8,11,null,13,4,7,2,null,null,5,1], t…
阅读更多...
从 ChatGPT 爆火回溯 NLP 技术

从 ChatGPT 爆火回溯 NLP 技术

ChatGPT 火遍了全网&#xff0c;多个话题频频登上热搜。见证了自然语言处理&#xff08;NLP&#xff09;技术的重大突破&#xff0c;体验到通用技术的无限魅力。GPT 模型是一种 NLP 模型&#xff0c;使用多层变换器&#xff08;Transformer&#xff09;来预测下一个单词的概率分…
阅读更多...
cuda编程以及GPU基本知识

cuda编程以及GPU基本知识

目录CPU与GPU的基本知识CPU特点GPU特点GPU vs. CPU什么样的问题适合GPU&#xff1f;GPU编程CUDA编程并行计算的整体流程CUDA编程术语&#xff1a;硬件CUDA编程术语&#xff1a;内存模型CUDA编程术语&#xff1a;软件线程块&#xff08;Thread Block&#xff09;网格&#xff08…
阅读更多...
新界面Moonbeam DApp上线，替你先尝试了一番！

新界面Moonbeam DApp上线，替你先尝试了一番！

作者&#xff1a;充电中的小恐龙 请注意&#xff0c;本篇内容来自Moonbeam社区成员的无偿分享&#xff0c;与Moonbeam官方和Moonbeam中文社区无关。本文内容仅供参考&#xff0c;对于内容的准确性和实效性&#xff0c;请自行谨慎判断。 本文撰写于DApp上线Beta版本之时&#…
阅读更多...
数据库开发（一文概括mysql基本知识）

数据库开发（一文概括mysql基本知识）

Mysql 是最流行的关系型数据库管理系统&#xff0c;在 WEB 应用方面 MySQL 是最好的 关系型数据库(Relational Database Management System&#xff1a;关系数据库管理系统)应用软件之一。mysql在问开发中&#xff0c;几乎必不可少&#xff0c;因为其他的可能是要收费的&#x…
阅读更多...
【运维】Linux定时任务 定时执行脚本

【运维】Linux定时任务 定时执行脚本

【运维】Linux定时任务 定时执行脚本 在安装完成操作系统后&#xff0c;默认会安装 crond 服务工具&#xff0c;且 crond 服务默认就是自启动的。crond 进程每分钟会定期检查是否有要执行的任务&#xff0c;如果有&#xff0c;则会自动执行该任务。 五分钟执行一次sh脚本 进入编…
阅读更多...
taobao.item.update.delisting( 商品下架 )

taobao.item.update.delisting( 商品下架 )

&#xffe5;开放平台基础API必须用户授权 单个商品下架输入的num_iid必须属于当前会话用户 公共参数 请求地址: HTTP地址 http://gw.api.taobao.com/router/rest 公共请求参数: 公共响应参数: 点击获取key和secret 请求参数 响应参数 请求示例 TaobaoClient client new …
阅读更多...
6-3 SpringCloud快速开发入门: Feign实现负载均衡的服务消费

6-3 SpringCloud快速开发入门: Feign实现负载均衡的服务消费

Feign实现负载均衡的服务消费 负载均衡&#xff1a;Spring Cloud 提供了 Ribbon来实现负载均衡&#xff0c;使用 Ribbo直接注入一个 RestTemplate对象即可&#xff0c;RestTemplate已经做好了负载均衡的配置&#xff1b; 在 Spring Cloud下&#xff0c;使用 Feign也是直接可以实…
阅读更多...
实时的软件生成 —— Prompt 编程打通低代码的最后一公里？

实时的软件生成 —— Prompt 编程打通低代码的最后一公里？

PS&#xff1a;这也是一篇畅想&#xff0c;虽然经过了一番试验&#xff0c;依旧有一些不足&#xff0c;但是大体上站得住脚。传统的软件生成方式需要程序员编写大量的代码&#xff0c;然后进行测试、发布等一系列繁琐的流程。而实时生成技术则是借助人工智能技术&#xff0c;让…
阅读更多...
在CANoe/CANalyzer中观察CAN Message报文的周期Cycle

在CANoe/CANalyzer中观察CAN Message报文的周期Cycle

案例背景&#xff1a; 该篇博文将告诉您&#xff0c;如何直观的&#xff0c;图示化的&#xff0c;查看CAN网络中各CAN Message报文的周期变化。 优质博文推荐阅读&#xff08;单击下方链接&#xff0c;即可跳转&#xff09;&#xff1a; Vector工具链 CAN Matrix DBC CAN M…
阅读更多...
市场份额下降，股价暴跌，金山云要想实现盈利还需要更长的时间

市场份额下降，股价暴跌，金山云要想实现盈利还需要更长的时间

来源&#xff1a;猛兽财经 作者&#xff1a;猛兽财经 IPO后股价表现与估值变化 金山云&#xff08;KC&#xff09;于2020年5月在纳斯达克进行了IPO上市&#xff0c;当时IPO价格为17美元。根据S&P Capital IQ的数据&#xff0c;截至2020年6月1日&#xff0c;金山云的股价已…
阅读更多...
linux基本功系列之uname实战

linux基本功系列之uname实战

文章目录前言一. uname命令介绍二. 语法格式及常用选项三. 参考案例3.1 输出全部信息3.2 输出内核名称及版本3.3 输出网络节点的主机名3.4 输出主机硬件架构3.5 输出操作系统名称3.6 显示版本信息总结前言 大家好&#xff0c;又见面了&#xff0c;我是沐风晓月&#xff0c;本文…
阅读更多...
深度学习-【语义分割】学习笔记4 膨胀卷积（Dilated convolution）

深度学习-【语义分割】学习笔记4 膨胀卷积（Dilated convolution）

文章目录膨胀卷积为什么需要膨胀卷积gridding effect连续使用三次膨胀卷积——1连续使用三次膨胀卷积——2连续使用三次膨胀卷积——3Understanding Convolution for Semantic Segmentation膨胀卷积 膨胀卷积&#xff0c;又叫空洞卷积。 左边是普通卷积&#xff0c;右边是膨胀…
阅读更多...
python的多线程编程之锁

python的多线程编程之锁

1、 背景概述 在上篇文章中&#xff0c;主要讲述了python中的socket编程的一些基本方面&#xff0c;但是缺少关于锁的相关概念&#xff0c;从而在这篇文章中进行补充。 由于在python中&#xff0c;存在了GIL&#xff0c;也就是全局解释器锁&#xff0c;从而在每次进行获得cpu的…
阅读更多...
网络通信--Linux

网络通信--Linux

文章目录网络通信的基础通信模型IP地址和端口port网络套接字网络字节序初识UDP与TCP两种协议sockaddr结构体家族认识一些网络常用基础函数UDP实现简单通信TCP实现简单通信总结网络通信的基础 网络通信是建立在多层协议之下&#xff0c;最终利用数据传输线路进行数据通信。首先…
阅读更多...
Web Spider案例 网洛克 第三题 AAEncode加密 练习(七)

Web Spider案例 网洛克 第三题 AAEncode加密 练习(七)

声明 此次案例只为学习交流使用&#xff0c;抓包内容、敏感网址、数据接口均已做脱敏处理&#xff0c;切勿用于其他非法用途&#xff1b; 文章目录声明一、资源推荐二、逆向目标三、抓包分析 & 下断分析逆向3.1 抓包分析3.2 下断分析逆向拿到混淆JS代码3.3 AAEncode解决方…
阅读更多...
【强烈建议收藏:MySQL面试必问系列之SQL语句执行专题】

【强烈建议收藏:MySQL面试必问系列之SQL语句执行专题】

一.知识回顾 之前的文章我们一起学习了MySQL面试必问系列之事务专题、锁专题&#xff0c;没有学习的小伙伴可以直接通过该链接地址直接访问&#xff0c;MYSQL你真的了解吗专栏的文章&#xff0c;接下来我们就一起来学习一下MySQL中SQL语句的执行流程&#xff0c;看看你掌握的怎…
阅读更多...
csdn文章导航

csdn文章导航

这里写自定义目录标题欢迎使用Markdown编辑器新的改变功能快捷键合理的创建标题&#xff0c;有助于目录的生成如何改变文本的样式插入链接与图片如何插入一段漂亮的代码片生成一个适合你的列表创建一个表格设定内容居中、居左、居右SmartyPants创建一个自定义列表如何创建一个注…
阅读更多...
Windows11安装Anaconda遇到的一些bug的【解决方案】

Windows11安装Anaconda遇到的一些bug的【解决方案】

Windows11安装Anaconda遇到的一些bug的【解决方案】问题描述&#xff1a;CondaValueError: Malformed version string ~: invalid character(s)或者类似&#xff1a;CondaHTTPError解决思路&#xff1a;主要是换源的时候清华大学的路径不对&#xff0c;过时了。。。只需修改用户…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023