了解Swagger规范检查点

目录

检查 @Api注解

第一项：是否包含接口的文字描述、接口的类名

检查 @ApiOperation注解

第一项：是否包含HTTP请求方法(Get、Post等)

第二项：是否有对方法的简单描述

第三项：是否有对方法的详细描述

检查 @ApiResponses注解

第一项：Response状态为200时

1. 返回实体类时 

2. 返回非实体类时（Map、String、Int等），无需检查

第二项：Response状态非200时

1.是否有返回状态码（201、400等）

2．是否有Reason

3.是否有Response Model

检查 @ApiImplicitParams注解

第一项：Parameter是否有值 

第二项：description是否有值

第三项：Data Type是否有值

第四项：Parameter Type是否有值

---

一、检查 @Api注解

检查项如下图1所示：

第一项：是否包含接口的文字描述、接口的类名

    

图1

二、检查 @ApiOperation注解

检查三项，如下图2所示：

第一项：是否包含HTTP请求方法(Get、Post等)

        对应注解属性：httpMethod

第二项：是否有对方法的简单描述

        对应注解属性：value

第三项：是否有对方法的详细描述

         对应注解属性：notes

图2

三、检查 @ApiResponses注解

检查两项，如下图3所示：

第一项：Response状态为200时

1. 返回实体类时 

检查返回对象类是否包含：

属性（如code、message等）、

属性描述（状态码、描述等）

        对应注解：@ApiModel、@ApiModelProperty

2. 返回非实体类时（Map、String、Int等），无需检查

图3

第二项：Response状态非200时

检查3项，如下图4所示

1.是否有返回状态码（201、400等）

        对应注解属性：code

2．是否有Reason

        对应注解属性：message

3.是否有Response Model

如果返回对象为实体类，请根据第三检查点第一项所示检测，对应注解属性：response

图4

四、检查 @ApiImplicitParams注解

检查4项，Parameters参数可为空，如下图5、图6所示：

第一项：Parameter是否有值 

            对应注解属性：name

第二项：description是否有值

            对应注解属性：value

第三项：Data Type是否有值

            对应注解属性：dataType

第四项：Parameter Type是否有值

对应注解属性：prameterType

 当Parameter Type为body时：

1. 如果入参为实体类，那么Data Type必须有实体类的属性、属性描述、默认值

如图6、图7所示

1. 如果入参为Map等非实体类参数时，Data Type可以为空。如图8所示

图5

图6

图7

图8