swagger-core.v1.5.X ANNOTATIONS

@Api 将一个类标记为swagger资源类。默认情况下。swagger-core仅仅引入和内省被该注解标注的类并且忽略其他资源(JAX-RS节点,servlet等等)注:在swagger2.0中该注解被删除

authorizations  对应操作对象的 ‘security’ 字段。也就是声明需要的授权,然后在对应的方法上使用@Authorization。
hidden  从swagger文档中,将该资源隐藏。
value  隐式的支持操作标记。在tags有值的情况下不显示
tags  标签,用来对@Api标注的类做一些说明,代替description

@ApiModel 作用域类上 对于swagger模块提供额外的信息

description  对于类提供一个描述
discriminator  支持模型继承和多态性。这个字段名字被作为鉴别器。基于此字段,可以断言需要使用哪个子类型。
parent 为该模块提供一个父类来描述继承
value  为该模块提供一个代理名字
subTypes  一个继承该模块的子类数组
reference  指定对相应类型定义的引用,覆盖指定的任何其他元数据

@ApiModelProperty 作用与方法或者字段 添加和操作模型属性

allowableValues  限制改参数所能接收的值
allowEmptyValue  允许接收一个空值
dataType  数据类型
example  该属性值得例子
hidden  在该swagger模型定义中隐藏
name  在 swagger 中该属性的名字
value 对于该属性的一个简要说明
notes  当前版本中没有使用
position   显示的声明在swagger文档中属性的顺序
required   是否必须,true是必传参数

@ApiOperation 作用与方法和类 描述针对特定路径的操作或通常为HTTP方法。

value  必须设置  提供一个简要的说明
authorizations  对应操作对象的 ‘security’ 字段。也就是声明需要的授权,然后在对应的方法上使用@Authorization。
code  返回的HTTP status 
hidden  在操作列表中隐藏该操作
consumes  接受内容类型的逗号分隔值。例如,“application/json, application/xml”会建议这个API资源接受json和xml输入。
httpMethod   以什么样的方式访问该方法(GET,POST,PUT,DELETE,HEAD,OPTIONS,PATCH),与MVC使用时会识别@Requestmapping中的HTTP.method
ignoreJsonView  忽略@JsonView注解解析操作和类型
notes   操作的详细描述
produces   同consumes  
protocols  设置此操作的特定协议(方案)。可能的值https,http,ws,wss
tags  API文档控制标签列表。

@Tag 作用域注解类型 定义一个标记对象

name  tag 名称
description   简单描述

@ApiParam 作用域类、方法、字段 (该批注只能与JAX-RS 1.x / 2.x批注结合使用)

@ApiImplicitParam 该注释必须作用在 @ ApiImplicitParams 中才会被解析

value   一个简要描述
dataType  请求参数的类型
required  是否必须
name   在方法参数中 需要特别说明的参数名称
defaultValue    默认值
allowableValues 允许的值 
allowMultiple  是否允许多个 
paramType 参数的参数类型 可能的值(path, query, body, header or form)

特别注意:allowableValues 多值设定方法

  1. 要设置值列表,请提供一个逗号分隔的列表。 例如:第一,第二,第三。
  2. 要设置值的范围,请以 “range” 开头,并用方括号括起来包括最小值和最大值,或者用圆括号括起来以表示最小值和最大值。 例如:range [1,5],range(1,5),range [1,5)。
  3. 要设置最小值/最大值,和(2)使用相同的格式,但将“ infinity”或“ -infinity”用作第二个值。 例如,range [1,infinity]表示此参数的最小允许值为1。
# java  swagger 

评论

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×