swagger-core.v1.5.X ANNOTATIONS

doMore 889 2019-10-12

@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