Swagger Java注解与JSON代码的对应总结
一、JSON、JAVA注释对比说明
1、@Api
注释在Control层，作用在类上面，对Control层进行描述
| 属性 | 说明 | 备注 |
|---|---|---|
| tags | 声明分组 | |
| value | ||
| description |
example :
JAVA注释：
@Api(tags="TEST",description="TEST Control")
public class TestImple{
...
}
对应的JSON文件：
{
......
"tags": [
{
"name": "TEST",
"description": "TEST Control"
}
]
......
}
2、@ApiOperation, @ApiParam
@ApiOperation
注释在Control层，作用在方法上，对API进行简要描述
| 属性 | 说明 | 备注 |
|---|---|---|
| value | 简短的说明 | |
| notes | 详细的description | |
| tags | 通过该属性对API进行分组 | |
| response | 返回类的model，可以直接引用一个类 | 非必填，可以在ApiResponse中进行分开定义 |
| responseContainer | 标注返回类的类型，只用于提示，不检查 | 同上 |
@ApiParam
注释在Control层，作用于参数上，针对参数进行描述
| 属性 | 说明 | 备注 |
|---|---|---|
| value | 对参数的说明 | |
| name | 请求参数的名字 | 可覆盖自动获取到的类名 |
| required | 请求参数是否必要 |
example :
JAVA注释：
@ApiOperition(value="short description",notes="detailed description",tags="TEST")
@PostMapping(value = "/api/testSwagger")
public String testSwagger(@RequestBody @ApiParam(name = "body",value="body",required = true) TestBody testParam)
对应的JSON文件:
{
......
"paths": {
"/api/testSwagger": {
"post": {
"tags": [
"TEST"
],
"summary": "short description",
"description": "detailed description",
"operationId": "short descriptionUsingPOST",
"consumes": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "body",
"required": true,
"schema": {
"$ref": "#/definitions/TestBody"//这里表示引入Model，通过@ApiModel注入
}
}
]
}
}
}
......
}
3、@ApiImpplicitParams, @ApiImplicaitParam
注释在Control层，作用于方法上，用于描述单独的参数
当有多个单独参数时，使用@ApiImplicitParams进行包裹
一个参数也建议包裹起来，便于后期添加新的参数
@ApiImplicatParam
| 属性 | 说明 | 备注 |
|---|---|---|
| name | 参数名 | |
| value | 参数描述，对应description | |
| required | 参数是否必需 | 会在页面生成红色星号提醒 |
| dataType | 参数数据类型 | 仅作为提示作用，不进行校验，覆盖自动获取的数据类型 |
| defaultValue | 默认值 | |
| paramType | 参数位置，放在哪里 | 见下表 |
paramType :
| 属性 | 说明 | 备注 |
|---|---|---|
| query | 参数随地址，自动映射 | |
| body | 参数以流的形式提交 | 只支持Post，较鸡肋，不推荐 |
| header | 参数在header中 | |
| form | 以表单提交 | 只支持Post |
当代码中使用@RequestBody接收数据的时候，建议采用@ApiModel进行参数设置
example :
JAVA注释：
@ApiImplicitParams({
@ApiImplicitParam(paramType = "header", name = "Content-Type", defaultValue = "application/json", required = true ,value = "header param")
})
public String testSwagger(@RequestBody @ApiParam(name = "body",value="body",required = true) TestBody testParam)
对应的JSON文件：
{
......
"paths": {
"/sap/ems/api/testSwagger": {
"post": {
......
"parameters": [
{
"in": "body",
"name": "body",
"description": "body",
"required": true,
"schema": {
"$ref": "#/definitions/TestBody"
}
},
{
"name": "Content-Type",
"in": "header",
"description": "header param",
"required": true,
"type": "string",
"default": "application/json"
}
]
......
}
}
}
......
}
4、@ApiResponses, @ApiResponse
注释在Control层，作用于方法上，描述返回类型，多个Response时用@ApiResponses包裹,常用于标识异常状态码
| 属性 | 说明 | 备注 |
|---|---|---|
| code | 返回的状态码 | |
| message | 返回状态的描述 | |
| response | 返回状态的model | 可以直接赋值返回类，自动解析 |
example :
JAVA注释：
@ApiResponses(value = {
@ApiResponse(code = 201, message = "Created",response = IntegrationApiMessage.class),
@ApiResponse(code = 401, message = "Unauthorized"),
@ApiResponse(code = 403, message = "Forbidden"),
@ApiResponse(code = 404, message = "Not Found")
})
public ResponseEntity<IntegrationApiMessage<Object>> testSwagger(@RequestBody @ApiParam(name = "body",value="body",required = true) TestBody testParam)
对应的JSON文件：
"paths": {
"/sap/ems/api/testSwagger": {
"post": {
......
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/IntegrationApiMessage«object»"
}
},
"201": {
"description": "Created",
"schema": {
"$ref": "#/definitions/IntegrationApiMessage"
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
}
}
}
},
Swagger目前版本支持自动识别用@ApiOperation注释过的方法中的请求参数及返回类型，所以这里的200状态码是自动识别的
5、@ApiModel，@ApiModelProperty
@ApiModel:
注释在Dao层，作用在@RequestBody修饰的请求参数类上，用于声明一个模板类型，对应JSON中的definition
| 属性 | 说明 | 备注 |
|---|---|---|
| value | 为该Model提供一个备用名称 | 默认为类名 |
| description | 对Model进行描述 | |
| parent | 提供Model的父类 | 可以用来描述类的继承关系 |
@ApiModelProperty
注释在Dao层，作用在声明的变量上，用于声明Model中的参数结构
| 属性 | 说明 | 备注 |
|---|---|---|
| value | 对参数的描述 | 对应description，会在Model中生成简要的描述 |
| required | 是否必要 | 默认为否 |
| dataType | 对参数数据类型的描述 | 不进行校验,可覆盖从类中读取到的类型 |
| name | 参数名字 | 可以用于覆盖参数名，默认为原参数名 |
| allowbleValues | 提供枚举值 | 对应JSON中的enum，会根据该属性生成example |
| hidden | 是否隐藏 | 默认为否 |
| allowEmptyValue | 是否允许为空 | 默认为否 |
example :
JAVA注释
@ApiModel(value = "TestBody)
public class TestBody
{
@JsonProperty("Attribute")
@ApiModelProperty(value = "attribute", dataType = "string",allowableValues = "EntitlementNo,OfferingID",required = true)
private String attribute;
@JsonProperty("Operation")
@ApiModelProperty(value = "operation", dataType = "string",allowableValues = "eq,isnull")
private String operation;
@ApiModelProperty(value = "dataType", hidden = true)
private String dataType;
@JsonProperty("Values")
@ApiModelProperty(value = "values", dataType = "List")
private List<String> values;
@JsonProperty("SubQueryFilters")
@ApiModelProperty(value = "subQueryFilter", dataType = "List")
private List<QueryFilter> subQueryFilters;
}
对应的JSON文件
{
......
"definitions": {
"TestBody": {
"type": "object",
"required": [
"Attribute"
],
"properties": {
"Attribute": {
"type": "string",
"description": "attribute",
"enum": [
"EntitlementNO",
"OfferingID"
]
},
"Operation": {
"type": "string",
"description": "operation",
"enum": [
"eq",
"isnull"
]
},
"SubQueryFilters": {
"type": "array",
"description": "subQueryFilter",
"items": {
"$ref": "#/definitions/QueryFilter"
}
},
"Values": {
"type": "array",
"description": "values",
"items": {
"type": "string"
}
}
}
}
}
......
}