文章 39
评论 3
浏览 384126
Swagger 注解

Swagger 注解

常用注解:

swagger是通过扫描很多的注解来获取数据帮我们展示在ui界面上的,下面就介绍下常用的注解。

注释汇总

对应关系为:

swagger2OpenAPI 3注解位置
@Api@Tag(name = “接口类描述”)Controller 类上
@ApiOperation@Operation(summary =“接口方法描述”)Controller 方法上
@ApiImplicitParams@ParametersController 方法上
@ApiImplicitParam@Parameter(description=“参数描述”)Controller 方法上 @Parameters
@ApiParam@Parameter(description=“参数描述”)Controller 方法的参数上
@ApiIgnore@Parameter(hidden = true)@Operation(hidden = true)@Hidden-
@ApiModel@SchemaDTO类上
@ApiModelProperty@SchemaDTO属性上
作用范围API使用位置
对象属性@ApiModelProperty用在出入参数对象的字段上
协议集描述@Api用于controller类上
协议描述@ApiOperation用在controller的方法上
Response集@ApiResponses用在controller的方法上
Response@ApiResponse用在 @ApiResponses里边
非对象参数集@ApiImplicitParams用在controller的方法上
非对象参数描述@ApiImplicitParam用在@ApiImplicitParams的方法里边
描述返回对象的意义@ApiModel用在返回对象类上
  1. @Api():用在请求的类上,表示对类的说明,也代表了这个类是swagger2的资源

参数:

tags:说明该类的作用,参数是个数组,可以填多个。
value="该参数没什么意义,在UI界面上不显示,所以不用配置"
description = "用户基本信息操作"
  1. @ApiOperation():用于方法,表示一个http请求访问该方法的操作

参数:

value="方法的用途和作用"    
notes="方法的注意事项和备注"    
tags:说明该方法的作用,参数是个数组,可以填多个。
格式:tags={"作用1","作用2"} 
(在这里建议不使用这个参数,会使界面看上去有点乱,前两个常用)
  1. @ApiModel():用于响应实体类上,用于说明实体作用

参数:

description="描述实体的作用"
  1. @ApiModelProperty:用在属性上,描述实体类的属性

参数:

value="用户名"  描述参数的意义
name="name"    参数的变量名
required=true     参数是否必选
  1. @ApiImplicitParams:用在请求的方法上,包含多@ApiImplicitParam
  2. @ApiImplicitParam:用于方法,表示单独的请求参数

参数:

name="参数ming" 
value="参数说明" 
dataType="数据类型" 
paramType="query" 表示参数放在哪里
    · header 请求参数的获取:@RequestHeader
    · query   请求参数的获取:@RequestParam
    · path(用于restful接口) 请求参数的获取:@PathVariable
    · body(不常用)
    · form(不常用) 
defaultValue="参数的默认值"
required="true" 表示参数是否必须传
  1. @ApiParam():用于方法,参数,字段说明 表示对参数的要求和说明

参数:

name="参数名称"
value="参数的简要说明"
defaultValue="参数默认值"
required="true" 表示属性是否必填,默认为false
  1. @ApiResponses:用于请求的方法上,根据响应码表示不同响应

一个@ApiResponses包含多个@ApiResponse

  1. @ApiResponse:用在请求的方法上,表示不同的响应

参数

code="404"    表示响应码(int型),可自定义
message="状态码对应的响应信息"

10、@ApiIgnore():用于类或者方法上,不被显示在页面上

11、@Profile({"dev", "test"}):用于配置类上,表示只对开发和测试环境有用


标题:Swagger 注解
作者:T-Aoker
地址:https://aoaos.top/articles/2021/01/29/1611906018085.html

修仙猿之旅

取消