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、@ApiImplicatParams, @ApiImplicatParam

注释在Control层，作用于方法上，用于描述单独的参数
当有多个单独参数时，使用@ApiImplicatParams进行包裹

一个参数也建议包裹起来，便于后期添加新的参数

@ApiImplicatParam

属性	说明	备注
name	参数名
value	参数描述，对应description
required	参数是否必需	会在页面生成红色星号提醒
dataType	参数数据类型	仅作为提示作用，不进行校验，覆盖自动获取的数据类型
defaultValue	默认值
paramType	参数位置，放在哪里	见下表

paramType :

属性	说明	备注
query	参数随地址，自动映射
body	参数以流的形式提交	只支持Post，较鸡肋，不推荐
header	参数在header中
form	以表单提交	只支持Post

当代码中使用@RequestBody接收数据的时候，建议采用@ApiModel进行参数设置

example :

JAVA注释：

@ApiImplicatParams({
    @ApiImplicatParam(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"
                    }
                }
            }
        }
    }

    ......
}