Springboot和Swagger使用入参显示踩的坑

1、使用实体作为入参，实体内存在List实体参数，参数显示不全的坑

入参类型：

@Data
@ApiModel("测试参数")
public class TestAo {

    @ApiModelProperty(value = "id", required = true, example = "1001")
    private String id;

    @ApiModelProperty(value = "请求具体参数", required = true)
    private List<UserAo> userAos;
}

@Data
@ApiModel("请求具体参数")
public class UserAo {

    @ApiModelProperty(value = "userName", required = true, example = "李四")
    private String userName;

    @ApiModelProperty(value = "password", required = true, example = "123456")
    private String password;

    @ApiModelProperty(value = "email", required = false, example = "123456")
    private String email;

    @ApiModelProperty(value = "age", required = true, example = "20")
    private String age;

    @ApiModelProperty(value = "sex", required = true, example = "男")
    private String sex;

    @ApiModelProperty(value = "score", required = true, example = "120")
    private String score;

    @ApiModelProperty(value = "classNo", required = true, example = "7")
    private String classNo;

    @ApiModelProperty(value = "like", required = true, example = "游泳")
    private String like;

    @ApiModelProperty(value = "game", required = true, example = "game")
    private String game;

    @ApiModelProperty(value = "serialCode", required = false,example = "01")
    private String serialCode;

    @ApiModelProperty(value = "serialNo", required = false,example = "01")
    private String serialNo;

    @ApiModelProperty(value = "la", required = false,example = "01")
    private String la;

    @ApiModelProperty(value = "lb", required = false,example = "01")
    private String lb;

    @ApiModelProperty(value = "lc", required = false,example = "01")
    private String lc;

    @ApiModelProperty(value = "ld", required = false,example = "01")
    private String ld;

    @ApiModelProperty(value = "le", required = false,example = "01")
    private String le;

    @ApiModelProperty(value = "lf", required = false,example = "01")
    private String lf;

    @ApiModelProperty(value = "lj", required = false,example = "01")
    private String lj;

    @ApiModelProperty(value = "lh", required = false,example = "01")
    private String lh;

    @ApiModelProperty(value = "li", required = false,example = "01")
    private String li;
}

上面写法Swagger ui可能会以下面格式显示：

{
	  "id": 1001,
	  "userAos": []，
	  "age": 20,
      "classNo": 7,
      "email": 123456,
      "game": "game",
      "la": "01",
      "lb": "01",
      "lc": "01",
      "ld": "01",
      "le": "01",
      "lf": "01",
      "lh": "01",
      "li": "01",
      "like": "游泳",
      "lj": "01",
      "password": 123456,
      "score": 120,
      "serialCode": "01",
      "serialNo": "01",
      "sex": "男",
      "userName": "李四"
}

解决方式：入参实体只能包含一个@ApiParam注解，把 UserAo类上的@ApiParam注解去除调，只保留TestAo上的@ApiParam注解就可以了，这样就能保证数据显示正常

调用类型：(显示参数前注解需要使用@RequestBody【json格式显示】或@ModelAttribute【页面列表显示分层参数不适用】)

	@ApiOperation(value = "测试接口")
    @ApiResponses({@ApiResponse(code = 200,message = "响应值详见[R]")})
    @PostMapping("/test")
    public R testApi(@ApiParam(value = "请求参数封装详见[TestAo]") @RequestBody TestAo testAo);

2、Swagger注解

集成需要请参见
SpringBoot集成springfox-swagger2构建restful API
SpringMVC集成springfox-swagger2构建restful API
GitHub官网地址
常用注解：

• @Api()用于类，表示标识这个类是swagger的资源；
  tags–表示说明
  value–也是说明，可以使用tags替代
• @ApiOperation()用于方法，表示一个http请求的操作；
  value用于方法描述
  notes用于提示内容
  tags可以重新分组（视情况而用）
• @ApiParam()用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）；
  name–参数名
  value–参数说明
  required–是否必填
• @ApiModel()用于类 ，表示对类进行说明，用于参数用实体类接收
  value–表示对象名
  description–描述
  都可省略
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
  value–字段说明
  name–重写属性名字
  dataType–重写属性类型
  required–是否必填
  example–举例说明
  hidden–隐藏
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
• name–参数ming
  value–参数说明
  dataType–数据类型
  paramType–参数类型
  example–举例说明