Swagger注解的使用


本文内容所使用的的Swagger版本:2.8.0

Swagger注解整理

注解描述
EnableSwagger2用在类上,用于启动Swagger
ApiIgnore用在类、方法、参数上,表示这个类或者方法被忽略(不需要swagger处理)
Api用在类上,对请求类进行描述。标识一个Controller类是Swagger文档类
ApiOperation用在方法上,对请求方法进行描述
ApiImplicitParams在方法上,对请求参数列表进行描述。其中的value属性可包含多个@ApiImplicitParam,对每个参加进行具体的描述
ApiImplicitParam用在方法上,对请求参数进行描述。当需要对多个参数进行描述时,作为@ApiImplicitParams的属性使用
ApiParam用在方法、参数、类的字段上,对请求参数进行描述
ApiModel用在类上,对请求、响应类进行描述
ApiModelProperty用在字段上,对请求、响应类的字段进行描述
ApiResponses用在方法、类上,对响应状态码列表进行描述
Example用在注解类型上,用于描述示例属性列表信息。一般作为@ApiImplicitParam、@ApiParam的属性使用
ExampleProperty用在注解类型上,用于描述示例属性信息。一般作为@Example的属性使用
Extension用在注解类型上,用于描述扩展选项信息。一般作为@ApiOperation、@Info、@Tag的属性使用
ExtensionProperty用在注解类型上,用于描述扩展选项的属性信息。一般作为@Extension的属性使用
SwaggerDefinition定义metadata level时使用,在Rest接口或类上使用
Tag用在注解类型上,用于对单个Apis和ApiOperations的全局标记。一般作为@SwaggerDefinition的属性使用
ExternalDocs用在参数、方法、属性上,使用外部文档说明的时候使用。一般作为@SwaggerDefinition、@Tag的属性使用
Info用在注解类型上,为swagger定义常规元数据。一般作为@SwaggerDefinition的属性使用
Contact用在注解类型上,配置API的可选联系信息。一般作为@Info的属性使用
License用在注解类型上,配置API的可选许可证信息。一般作为@Info的属性使用
Authorization用在方法上,进行接口授权。一般作为@Api或@ApiOperation的属性使用
AuthorizationScope用在方法上,描述接口授权范围。一般作为@Authorization的属性使用
ApiKeyAuthDefinitionOAuth安全定义对象
BasicAuthDefinition基本身份验证安全定义对象
OAuth2DefinitionOAuth安全定义对象
Scope用于指定作用范围,一般作为@OAuth2Definition的属性使用

1. 启动Swagger注解

@EnableSwagger2

用在上,启动Swagger。

2. 请求类方法描述注解

@ApiIgnore

用在类、方法、参数上,表示这个类或者方法被忽略(不需要swagger处理)。

注解的属性

属性名称属性类型属性默认值属性描述
valueString""简要说明忽略的原因

@Api

用在上,对请求类进行描述。标识一个Controller类是Swagger文档类。

注解的属性

属性名称属性类型属性默认值属性描述
valueString""描述,无实际意义。
tagsString[]""分组
descriptionString""描述(已弃用)
basePathString""基本路径(已弃用)已无效
positionint0显示顺序(已弃用)已无效
producesStringint输出数据内容类型(已弃用)已无效
consumesStringint输入数据内容类型(已弃用)已无效
protocolsStringint请求协议
authorizationsAuthorization[]@Authorization(value = "")高级特性认证时的配置
hiddenbooleanfalse是否隐藏(不显示)
  1. 注解属性value、tags二者的区别

    1. value属性作用在类和作用在方法上都用于描述;

    2. tags属性作用在类和作用在方法上都用于分组,但分组的效果区别很大:

      1. tags作用在类上时,会对全局的方法分组,即根据tags属性值复制多份,此时方法上的tags值无效,方法上tags配或不配效果都一样。

      2. tags作用在方法上时,会根据当前类的所有方法的tags值做分组,粒度更细。

属性包含的注解

  • @Authorization

使用方法

@RestController
@RequestMapping(value = "swaggerTest")
@Api(tags = "Swagger测试相关接口",description = "Swagger测试相关接口的描述")
public class SwaggerTestController {

}

@ApiOperation

用在方法上,对请求方法进行描述。

注解的属性

属性名称属性类型属性默认值属性描述
valueString描述
notesString""详细描述
tagsString[]""分组
responseClass<?>Void.class响应参数类型
responseContainerString""该属性对这些对象是有效的:List、Set、Map,其他无效。
responseReferenceString""指定对响应类型的引用,本地/远程引用,并将覆盖任何其它指定的response()类
httpMethodString""http请求方式,如:GET、HEAD、POST、PUT、DELETE、OPTION、SPATCH
positionint0显示顺序(已弃用)已无效
nicknameString""第三方工具使用operationId来唯一表示此操作
producesString""输出数据内容类型,如:application/json,application/xml(多个用英文逗号隔开)
consumesString""输入数据内容类型,如:application/json,application/xml(多个用英文逗号隔开)
protocolsString""请求协议
authorizationsAuthorization[]@Authorization(value = "")高级特性认证时的配置
hiddenbooleanfalse是否隐藏(不显示)
responseHeadersResponseHeader[]@ResponseHeader(name = "", response = Void.class)响应头信息,@ResponseHeader数组
codeint200http的状态码
extensionsExtension[]@Extension(properties = @ExtensionProperty(name = "", value = "")扩展属性

属性包含的注解

  • @Authorization
  • @ResponseHeader
  • @Extension

使用方法

    @GetMapping("test1")
    @ApiOperation(value = "test1接口",notes = "test1接口详细描述")
    public ApiResult<String> test1(@RequestParam String aa, @RequestParam String bb, @RequestParam String cc) {
        return ApiUtil.success("success");
    }

3. 请求参数描述注解

@ApiImplicitParams

常用在方法上,对请求参数列表进行描述。
其中的value属性可包含多个@ApiImplicitParam,对每个参加进行具体的描述。

注解的属性

属性名称属性类型属性默认值属性描述
valueApiImplicitParam[]参数列表描述

属性包含的注解

  • @ApiImplicitParam

@ApiImplicitParam

用在方法上,对请求参数进行描述。当需要对多个参数进行描述时,作为@ApiImplicitParams的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
nameString""参数名
valueString""参数说明
defaultValueString""默认值
allowableValuesString""参数允许值
requiredbooleanfalse是否必填
accessString""参数过滤
allowMultiplebooleanfalse参数是否可以通过多次出现来接受多个值,默认不允许
dataTypeString""参数的数据类型,可以使类名或原始数据类型
dataTypeClassClass<?>Void.class参数的数据类型,如果提供则覆盖 dataType
paramTypeString""参数类型,有效值为 path, query, body, header, form
exampleString""非body类型的参数示例
examplesExample@Example(value = @ExampleProperty(mediaType = “”, value = “”))body类型的参数示例
typeString""添加覆盖检测到的类型的功能
formatString""添加提供自定义format格式的功能
allowEmptyValuebooleanfalse添加将格式设置为空的功能
readOnlybooleanfalse添加被指定为只读的功能
collectionFormatString""添加使用array类型覆盖collectionFormat的功能

属性包含的注解

  • @Example

属性paramType取值

  • header :通过@RequestHeader获取
  • query:通过@RequestParam获取
  • path:通过@PathVariable获取
  • body:通过@RequestBody获取
  • form:通过@RequestParam获取

使用方法

    @GetMapping("test1")
    @ApiOperation(value = "test1接口",notes = "test1接口详细描述")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "aa",value = "aa的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
            @ApiImplicitParam(name = "bb",value = "bb的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
            @ApiImplicitParam(name = "cc",value = "cc的说明",defaultValue = "2",allowableValues = "1,2,3",required = true),

    })
    public ApiResult<String> test1(@RequestParam String aa, @RequestParam String bb, @RequestParam String cc) {
        return ApiUtil.success("success");
    }

@ApiParam

用在方法、参数、类的字段上,对请求参数进行描述。

注解的属性

属性名称属性类型属性默认值属性描述
nameString""参数名
valueString""参数说明
defaultValueString""默认值
allowableValuesString""参数允许值
requiredbooleanfalse是否必填
accessString""参数过滤
allowMultiplebooleanfalse参数是否可以通过多次出现来接受多个值,默认不允许
hiddenbooleanfalse是否隐藏(不显示),默认false
exampleString""非body类型的参数示例
examplesExample@Example(value = @ExampleProperty(mediaType = "", value = ""))body类型的参数示例
typeString""添加覆盖检测到的类型的功能
formatString""添加提供自定义format格式的功能
allowEmptyValuebooleanfalse添加将格式设置为空的功能
readOnlybooleanfalse添加被指定为只读的功能
collectionFormatString""添加使用array类型覆盖collectionFormat的功能

属性包含的注解

  • @Example

使用方法

    @GetMapping("test2")
    @ApiOperation(value = "test2接口",notes = "test2接口详细描述")
    public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
        return ApiUtil.success(new TestRes());
    }

4. 对象描述(请求响应)注解

@ApiModel

用在上,对请求、响应类进行描述。

注解的属性

属性名称属性类型属性默认值属性描述
valueString""为提供模型的替代名称,默认情况下,使用类名
descriptionString""类的描述
parentClass<?> parentVoid.class为模型提供父类以允许描述继承关系
discriminatoryString""支持模型继承和多态,使用鉴别器的字段的名称,可以断言需要使用哪个子类型
subTypesClass<?>[]{}从此模型继承的子类型数组
referenceString""指定对应类型定义的引用,覆盖指定的任何其他元数据

@ApiModelProperty

常用在字段上,对请求、响应类的字段进行描述。

注解的属性

属性名称属性类型属性默认值属性描述
nameString""覆盖属性的名称
valueString""属性说明
allowableValuesString""参数允许值
accessString""过滤属性
notesString""目前尚未使用
dataTypeString""参数的数据类型,可以使类名或原始数据类型
requiredbooleanfalse是否必填
positionint0显示顺序
hiddenbooleanfalse是否隐藏
exampleString""属性的示例值
readOnlybooleanfalse添加被指定为只读的功能
referenceString""指定对应类型定义的引用,覆盖指定的任何其他元数据
allowEmptyValuebooleanfalse允许传空值

使用方法

@Data
@ApiModel(description = "测试请求类")
public class TestReq {

    @ApiModelProperty(value = "用户ID",required = true)
    private Long userId;
    @ApiModelProperty(value = "用户名",example = "张三")
    private String userName;
    @ApiModelProperty(value = "性别:1男、2女")
    private Integer sex;
    @ApiModelProperty(value = "昵称")
    private String nickName;
    @ApiModelProperty(value = "邮箱")
    private String email;
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
}
@Data
@ApiModel(description = "测试响应类")
public class TestRes {

    @ApiModelProperty(value = "用户ID",required = true)
    private Long userId;
    @ApiModelProperty(value = "用户名")
    private String userName;
    @ApiModelProperty(value = "性别:1男、2女")
    private Integer sex;
    @ApiModelProperty(value = "昵称")
    private String nickName;
    @ApiModelProperty(value = "邮箱")
    private String email;
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
}

5. 响应参数描述注解

@ApiResponses

用在方法、类上,对响应状态码列表进行描述。
注解的属性

属性名称属性类型属性默认值属性描述
valueApiResponse[]响应状态码列表的描述

属性包含的注解

  • @ApiResponse

@ApiResponse

用在方法上,对响应状态码进行描述。一般作为@ApiResponses的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
codeint响应的HTTP状态码
messageString响应的描述
responseClass<?>Void.class用于描述消息有效负载的可选响应类,对应于响应消息对象的 schema 字段
referenceString""指定对响应类型的引用,指定的应用可以使本地引用,也可以是远程引用,将按原样使用,并将覆盖任何指定的response()类
responseHeadersResponseHeader[]@ResponseHeader(name = "", response = Void.class)可能响应的header列表
responseContainerString""声明响应的容器,有效值为List,Set,Map,任何其他值都将被忽略

属性包含的注解

  • @ResponseHeader

@ResponseHeader

用在方法上,对响应头信息进行描述。一般作为@ApiResponse的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
nameString""响应头参数名称
descriptionString""响应头参数详细描述
responseClass<?>Void.class响应头数据类型
responseContainerString""声明包装响应的容器,有效值为List或Set,任何其他值都将被覆盖

使用方法

    @GetMapping("test2")
    @ApiOperation(value = "test2接口",notes = "test2接口详细描述")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "请求成功", responseHeaders = {@ResponseHeader(name = "header1", description = "header1的描述",response = String.class)}),
            @ApiResponse(code = 401, message = "没有权限"),
            @ApiResponse(code = 403, message = "禁止访问")
    })
    public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
        return ApiUtil.success(new TestRes());
    }

6. 示例信息注解

@Example

用在注解类型上,用于描述示例属性列表信息。一般作为@ApiImplicitParam、@ApiParam的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
valueExampleProperty[]示例的属性信息集合

属性包含的注解

  • @ExampleProperty

@ExampleProperty

用在注解类型上,用于描述示例属性信息。一般作为@Example的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
mediaTypeString“default”属性名称
valueString属性值

7. 扩展信息注解

@Extension

用在注解类型上,用于描述扩展选项信息。一般作为@ApiOperation、@Info、@Tag的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
nameString""扩展的选项名称
propertiesExtensionProperty[]扩展选项的属性集合

属性包含的注解

  • @ExtensionProperty

@ExtensionProperty

用在注解类型上,用于描述扩展选项的属性信息。一般作为@Extension的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
nameString属性名称
valueString属性值

8. Swagger配置相关注解

①、Swagger配置注解

@SwaggerDefinition

定义metadata level时使用,在Rest接口或类上使用。

注解的属性

属性名称属性类型属性默认值属性描述
hostString""要在生成的Swagger定义中指定的主机
basePathString""指定生成的Swagger文档定义basePath
consumesString[]""
producesString[]""
schemesScheme[]Scheme.EFAULTAPI 的传输协议
tagsTag[]@Tag(name = "")可用于对单个Apis和ApiOperations的全局标记
securityDefinitionSecurityDefinition@SecurityDefinition()安全方案的定义
infoInfo@Info(title = "", version = "")为swagger定义常规元数据
externalDocsExternalDocs@ExternalDocs(url = "")外部文档

属性包含的注解

  • @Tag
  • @ExternalDocs
  • @Info
  • @SecurityDefinition

②、标记信息注解

@Tag

用在注解类型上,用于对单个Apis和ApiOperations的全局标记。一般作为@SwaggerDefinition的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
nameString标记的名称
descriptionString""标记的描述
externalDocsExternalDocs@ExternalDocs(url = "")标记的外部文档参考选项
extensionsExtension[]@Extension(properties = @ExtensionProperty(name = "", value = "")扩展属性集合选项

属性包含的注解

  • @Extension

③、外部文档配置注解

@ExternalDocs

用在参数、方法、属性上,使用外部文档说明的时候使用。一般作为@SwaggerDefinition、@Tag的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
valueString""目标文档的简要描述,GFM语法可用于富文本表示
urlString引用文档的URL

④、元数据配置注解

@Info

用在注解类型上,为swagger定义常规元数据。一般作为@SwaggerDefinition的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
titleStringAPI的标题
versionStringAPI的版本
descriptionString""API的描述选项
termsOfServiceString""API的可选服务条款
contactContact@Contact(name = "")API的可选联系信息
licenseLicense@License(name = "")API的可选许可证信息
extensionsExtension[]@Extension(properties = @ExtensionProperty(name = "", value = ""))API的可选扩展列表信息

属性包含的注解

  • @Contact
  • @License
  • @ExternalDocs

⑤、联系人配置注解

@Contact

用在注解类型上,配置API的可选联系信息。一般作为@Info的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
nameString联系人名称
urlString""联系人关联URL
emailString""联系人邮箱

⑥、许可证配置注解

@License

用在注解类型上,配置API的可选许可证信息。一般作为@Info的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
nameString许可证名称
urlString""许可证关联URL

⑦、安全方案配置注解

@Authorization

用在方法上,进行接口授权。一般作为@Api或@ApiOperation的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
valueString要在此资源/操作上使用的授权方案名称。必须在资源列表的授权部分中定义名称
scopesAuthorizationScope[]@AuthorizationScope(scope = "", description = "")授权方案为OAuth2时使用的范围

属性包含的注解

  • @AuthorizationScope

@AuthorizationScope

用在方法上,描述接口授权范围。一般作为@Authorization的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
scopeString要使用的OAuth2授权方案的范围。范围应事先在Swagger对象的securityDefinition部分中声明
descriptionString在1.5.X中使用,保留用于旧版本的支持

@SecurityDefinition

用在注解类型上,用于安全方案的定义。一般作为@SwaggerDefinition的属性使用。

注解的属性

属性名称属性类型属性默认值属性描述
oAuth2DefinitionsOAuth2Definition[]{}OAuth安全定义对象集合
apiKeyAuthDefintionsApiKeyAuthDefinition[]{}已弃用
apiKeyAuthDefinitionsApiKeyAuthDefinition[]{}API Key安全定义对象集合
basicAuthDefinionsBasicAuthDefinition[]{}已弃用
basicAuthDefinitionsBasicAuthDefinition[]{}基本身份验证安全定义对象集合

@ApiKeyAuthDefinition

OAuth安全定义对象。

注解的属性

属性名称属性类型属性默认值属性描述
keyString用于引用此安全定义的密钥
descriptionString""安全方案的简短描述
inStringApiKeyLocationAPI 密钥的位置,有效值为query或header
nameString要使用的query或header参数的名称

@BasicAuthDefinition

基本身份验证安全定义对象。

注解的属性

属性名称属性类型属性默认值属性描述
keyString用于引用此安全定义的密钥
descriptionString""安全方案的简短描述

@OAuth2Definition

OAuth安全定义对象。

注解的属性

属性名称属性类型属性默认值属性描述
keyString用于引用此安全定义的密钥
descriptionString""安全方案的简短描述
flowFlowOAuth2 安全方案使用的流程。有效值为implicit、password、application、accessCode
authorizationUrlString""用于此流程的授权 URL。隐式和访问代码流需要
tokenUrlString""用于此流程的令牌 URL。密码、应用程序和访问代码流需要
scopesScope[]{}作用范围集合

属性包含的注解

  • @Scope

@Scope

注解的属性

属性名称属性类型属性默认值属性描述
nameString范围名称
descriptionString范围描述

注解使用完整源码

SwaggerTestController

@RestController
@RequestMapping(value = "swaggerTest")
@Api(tags = "Swagger测试相关接口",description = "Swagger测试相关接口的描述")
// @ApiIgnore(value = "不想在Swagger文档上显示")
public class SwaggerTestController {

    @GetMapping("test1")
    @ApiOperation(value = "test1接口",notes = "test1接口详细描述")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "aa",value = "aa的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
            @ApiImplicitParam(name = "bb",value = "bb的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
            @ApiImplicitParam(name = "cc",value = "cc的说明",defaultValue = "2",allowableValues = "1,2,3",required = true),
    })
    public ApiResult<String> test1(@RequestParam String aa, @RequestParam String bb, @RequestParam String cc) {
        return ApiUtil.success("success");
    }

    @GetMapping("test2")
    @ApiOperation(value = "test2接口",notes = "test2接口详细描述")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "请求成功", responseHeaders = {@ResponseHeader(name = "header1", description = "header1的描述",response = String.class)}),
            @ApiResponse(code = 401, message = "没有权限", responseHeaders = {@ResponseHeader(name = "header2", description = "header2的描述",response = String.class)}),
            @ApiResponse(code = 403, message = "禁止访问")
    })
    public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
        return ApiUtil.success(new TestRes());
    }

    @PostMapping("test3")
    @ApiOperation(value = "test3接口",notes = "test3接口详细描述")
    public ApiResult<TestRes> test3(@ApiParam(value = "请求类TestReq") @RequestBody TestReq req) {
        return ApiUtil.success(new TestRes());
    }
}

TestReq

@Data
@ApiModel(description = "测试请求类")
public class TestReq {

    @ApiModelProperty(value = "用户ID",required = true)
    private Long userId;
    @ApiModelProperty(value = "用户名",example = "张三")
    private String userName;
    @ApiModelProperty(value = "性别:1男、2女")
    private Integer sex;
    @ApiModelProperty(value = "昵称")
    private String nickName;
    @ApiModelProperty(value = "邮箱")
    private String email;
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
}

TestRes

@Data
@ApiModel(description = "测试响应类")
public class TestRes {

    @ApiModelProperty(value = "用户ID",required = true)
    private Long userId;
    @ApiModelProperty(value = "用户名")
    private String userName;
    @ApiModelProperty(value = "性别:1男、2女")
    private Integer sex;
    @ApiModelProperty(value = "昵称")
    private String nickName;
    @ApiModelProperty(value = "邮箱")
    private String email;
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
}
  • 11
    点赞
  • 58
    收藏
    觉得还不错? 一键收藏
  • 3
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 3
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值