Swagger2常用注解说明

2019-10-09| 发布者: admin| 查看: |

这里只讲述@api、@apioperation、@apiimplicitparams、@apiimplicitparam、@apiparam、@apimodel、@apimodelproperty、apiresponses、@apiresponse这几个常用的。
@api:用在请求的类上,表示对类的说明
常用参数:
tags="说明该类的作用,非空时将覆盖value的值"
value="描述类的作用"
其他参数:
description 对api资源的描述,在1.5版本后不再支持
basepath 基本路径可以不配置,在1.5版本后不再支持
position 如果配置多个api 想改变显示的顺序位置,在1.5版本后不再支持
produces 设置mime类型列表,例:"application/json, application/xml",默认为空
consumes 设置mime类型列表,例:"application/json, application/xml",默认为空
protocols 设置特定协议,例:http, https, ws, wss。
authorizations 获取授权列表,如果未设置,则返回一个空的授权值。
hidden 默认为false, 配置为true 将在文档中隐藏

示例:
@api
@controller
@requestmapping
public class logincontroller {}

@apioperation:用在请求的方法上,说明方法的用途、作用
常用参数:
value="说明方法的用途、作用"
notes="方法的备注说明"
其他参数:
tags 操作标签,非空时将覆盖value的值
response 响应类型
responsecontainer 声明包装的响应容器。有效值为 "list", "set" or "map"。
responsereference 指定对响应类型的引用。将覆盖任何指定的response类
httpmethod 指定http方法,"get", "head", "post", "put", "delete", "options" and "patch"
position 如果配置多个api 想改变显示的顺序位置,在1.5版本后不再支持
nickname 第三方工具唯一标识,默认为空
produces 设置mime类型列表,例:"application/json, application/xml",默认为空
consumes 设置mime类型列表,例:"application/json, application/xml",默认为空
protocols 设置特定协议,例:http, https, ws, wss。
authorizations 获取授权列表,如果未设置,则返回一个空的授权值。
hidden 默认为false, 配置为true 将在文档中隐藏
responseheaders 响应头列表
code 响应的http状态代码。默认 200
extensions 扩展属性列表数组

示例:
@responsebody
@postmapping
@apioperation
public usermodel login string account,
@requestparam string password){}


@apiimplicitparams:用在请求的方法上,表示一组参数说明
@apiimplicitparam:用在@apiimplicitparams注解中,指定一个请求参数的各个方面
name:参数名,参数名称可以覆盖方法参数名称,路径参数必须与方法参数一致
value:参数的汉字说明、解释
required:参数是否必须传,默认为false [路径参数必填]
paramtype:参数放在哪个地方
· header -- 请求参数的获取:@requestheader
· query -- 请求参数的获取:@requestparam
· path-- 请求参数的获取:@pathvariable
· body
· form
datatype:参数类型,默认string,其它值datatype="integer"
defaultvalue:参数的默认值

示例:
@responsebody
@postmapping
@apioperation
@apiimplicitparams,
@apiimplicitparam
})
public usermodel login string account,
@requestparam string password){}

其他参数:
allowablevalues 限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值
access 允许从api文档中过滤参数。
allowmultiple 指定参数是否可以通过具有多个事件接受多个值,默认为false
example 单个示例
examples 参数示例。仅适用于bodyparameters



@apimodel:用于响应类上,表示一个返回响应数据的信息
@apimodelproperty:用在属性上,描述响应类的属性
示例:
@apimodel
public class usermodel implements serializable{

private static final long serialversionuid = 1l;

/**
* 用户名
*/
@apimodelproperty
private string account;

/**
* 密码
*/
@apimodelproperty
private string password;


}
其他:
value 此属性的简要说明。
name 允许覆盖属性名称
allowablevalues 限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值
access 允许从api文档中过滤属性。
notes 目前尚未使用。
datatype 参数的数据类型。可以是类名或者参数名,会覆盖类的属性名称。
required 参数是否必传,默认为false
position 允许在类中对属性进行排序。默认为0
hidden 允许在swagger模型定义中隐藏该属性。
example 属性的示例。
readonly 将属性设定为只读。
reference 指定对相应类型定义的引用,覆盖指定的任何参数值



@apiresponses:用在请求的方法上,表示一组响应
@apiresponse:用在@apiresponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类

示例:
@responsebody
@postmapping
@apioperation
@apiresponses,
@apiresponse
})
public jsonresult update{}

@apiparam: 用在请求方法中,描述参数信息
name:参数名称,参数名称可以覆盖方法参数名称,路径参数必须与方法参数一致
value:参数的简要说明。
defaultvalue:参数默认值
required 属性是否必填,默认为false [路径参数必须填]

示例:
@responsebody
@postmapping
@apioperation
public usermodel login @requestparam string account,
@apiparam @requestparam string password){}


或以实体类为参数:
@responsebody
@postmapping
@apioperation
public usermodel login usermodel model){}

其他:
allowablevalues 限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值
access 允许从api文档中过滤参数。
allowmultiple 指定参数是否可以通过具有多个事件接受多个值,默认为false
hidden 隐藏参数列表中的参数。
example 单个示例
examples 参数示例。仅适用于bodyparameters

本文转载于爱吃醋的兔子