zoukankan      html  css  js  c++  java

  • spring boot 处理 swagger 嵌套数据展示

    spring boot 处理 swagger 嵌套数据展示

    在开发的过程中,我们会常常使用swagger做我们的在线文档.
    我们会在对象的属性上使用@ApiModelProperty 等api注解,但是遇到对象嵌套的时候,如何返回一个嵌套的json文档就需要我们做一些简单的处理

    如果只在对象某个属性上使用 @ApiModelProperty 并不会起作用

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    @Data
    @Slf4j
    @Builder
    @ApiModel(value = "统一数据返回对象", description = "所有数据经此包装")
    public class WebResult implements Serializable {

        public static final String REQUEST_STATUS_ERROR = "error";
        
        public static final String REQUEST_STATUS_SUCCESS = "success";
        
        private static final long serialVersionUID = 1L;
        
        /**
         * 状态码
         */
        @ApiModelProperty(required = true, value = "返回状态码", dataType = "int", example = "200", position = 0)
        private int code;
        
        /**
         * 返回数据
         */
        @ApiModelProperty(required = true, value = "返回数据", dataType = "string", example = "data", position = 1)
        private Object data;
        
        /**
         * msg信息
         */
        @ApiModelProperty(required = true, value = "返回message 信息", dataType = "string", example = "success", position = 2)
        private String message;

    }

    在设置统一返回时,如果仅仅把数据封装在Result对象的属性里, swagger并不会展示data内部的数据

    创建一个对象,加入我们的Result中,启动swagger,查看接口的文档

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    @ApiModel(value = "Person对象")
    public class Person {

        @ApiModelProperty("索引id")
        private Long id;

        @ApiModelProperty(value = "用户姓名")
        private String name;

        @ApiModelProperty(value = "密码")
        private String pwd;

        @ApiModelProperty(value = "备注")
        private String remark;
        
    }

    控制器

    1
    2
    3
    4
    5
    6
    7
    8
    9
    @ApiOperation(value = "获取person json返回值", notes = "该操作不会展示嵌套的数据注释")
        @PostMapping("/person")
        public WebResult findPerson() {
            return WebResult.builder()
                    .code(200)
                    .message(REQUEST_STATUS_SUCCESS)
                    .data(new Person(1, "myName", "123456", "测试数据"))
                    .build();
        }

    我们发现最后自动生成的文档里并没有我们需要的内嵌信息

    为了展示内嵌的数据对象进行泛型修改

    使用泛型指定的swagger,可以展示data的数据内部文档注释

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    @Data
    @Builder
    @ApiModel(value = "统一数据返回对象",
            description = "所有数据经此包装,使用了泛型,可展示泛型内的数据文档注释")
    public class WebProResult<T> implements Serializable {

        public static final String REQUEST_STATUS_ERROR = "error";
        public static final String REQUEST_STATUS_SUCCESS = "success";
        private static final long serialVersionUID = 1L;
        /**
         * 状态码
         */
        @ApiModelProperty(required = true, 
                          value = "返回状态码", 
                          dataType = "int", 
                          example = "200", position = 0)
        private int code;
        /**
         * 返回数据
         */
        @ApiModelProperty(required = true, 
                          value = "返回数据", 
                          dataType = "string", 
                          example = "data", position = 1)
        private T data;
        /**
         * msg信息
         */
        @ApiModelProperty(required = true, 
                          value = "返回message 信息", 
                          dataType = "string", 
                          example = "success", position = 2)
        private String message;

    }

    控制器的代码

    这里都用到了 lombok 的@Builder进行创建对象

    注意加上泛型之后的写法

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    @ApiOperation(value = "获取person json返回值", 
                  notes = "通过泛型指定,我们告诉了swagger属性内的对象是什么")
    @PostMapping("/person/pro")
    public WebProResult<Person> findPersonPro() {
        return WebProResult.<Person>builder()
                .code(200)
                .message(REQUEST_STATUS_SUCCESS)
                .data(new Person(1, "myName", "123456", "测试数据"))
                .build();
    }

    最后我们发现可以通过swagger得到所有加过的文档注释

    在接口的文档注释中,直接可以点开内部的信息

    通过泛型,即使是多个对象互相嵌套也可展示

    接口不单只获取一个对象,还有分页信息,添加一个拥有泛型的分页对象

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    @Data
    @Builder
    @ApiModel(value = "分页数据", description = "分页数据统一返回对象")
    public class PageVo<T> {

        @ApiModelProperty(value = "列表数据", 
                          dataType = "String", 
                          name = "values", example = "")
        private List<T> values;

        /**
         * 分页
         */
        @ApiModelProperty(value = "第几页", 
                          dataType = "int", 
                          name = "page", example = "1")
        private int page;
        
        /**
         * 分页值
         */
        @ApiModelProperty(value = "每页多少条", 
                          dataType = "int", 
                          name = "size", example = "10")
        private int size;
        
        /**
         * 一共查询了多少条数据
         */
        @ApiModelProperty(value = "一共查询了多少条数据", 
                          dataType = "long", 
                          name = "total", 
                          notes = "不需要传输 仅返回时展示使用")
        private long total;


    }

    控制器返回封装的分页信息,仍通过Result多层嵌套返回json

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    @ApiOperation(value = "获取person json返回值", notes = "通过泛型指定,多层嵌套也可展示")
    @PostMapping("/person/page")
    public WebProResult<PageVo<Person>> findPersonPage() {

        Person person = new Person(1, "myName", "123456", "测试数据");

        PageVo<Person> pageVo = PageVo.<Person>builder()
                .page(1)
                .size(10)
                .total(20)
                .values(Collections.singletonList(person))
                .build();

        return WebProResult.<PageVo<Person>>builder()
                .code(200)
                .message(REQUEST_STATUS_SUCCESS)
                .data(pageVo)
                .build();
    }

    swagger 多层嵌套返回了每一个内部对象的文档注释

    依此点开,可以看到内部信息

    github Demo

    源码地址

    https://github.com/1119264845/blog-examples

    原文地址：http://www.elfop.com/2019/07/24/springBoot%E6%95%B4%E5%90%88swagger%E5%B1%95%E7%A4%BA%E8%BF%94%E5%9B%9E%E5%AF%B9%E8%B1%A1%E7%9A%84%E5%B5%8C%E5%A5%97%E5%B1%9E%E6%80%A7%E6%96%87%E6%A1%A3%E6%B3%A8%E9%87%8A/#spring-boot-%E5%A4%84%E7%90%86-swagger-%E5%B5%8C%E5%A5%97%E6%95%B0%E6%8D%AE%E5%B1%95%E7%A4%BA
  • 相关阅读:
    mysql对表操作的各种语句
    Map遍历两种方式
    hibernate3
    Spring、mybaits整合
    mybaits注解
    mybaits 框架运用
    mybatis入门
    限制文本框字符数
    Unity3D Mathf函数
    Unity3d 粒子工具注释
  • 原文地址：https://www.cnblogs.com/jpfss/p/12084677.html
Copyright © 2011-2022 走看看