springBoot 整合 swagger 展示返回对象的嵌套属性文档注释

spring boot 处理 swagger 嵌套数据展示

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

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

12345678910111213141516171819202122232425262728293031
@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,查看接口的文档

12345678910111213141516
@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;

}

控制器

123456789
@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的数据内部文档注释

1234567891011121314151617181920212223242526272829303132333435
@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进行创建对象

注意加上泛型之后的写法

12345678910
@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得到所有加过的文档注释

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

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

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

12345678910111213141516171819202122232425262728293031323334353637
@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

12345678910111213141516171819
@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

原文地址:https://www.cnblogs.com/jpfss/p/12120541.html

时间: 2024-11-05 18:28:46

springBoot 整合 swagger 展示返回对象的嵌套属性文档注释的相关文章

六、springboot整合swagger

六.springboot整合swagger 简介 swagger 提供最强大,最易用的工具,以充分利用OpenAPI规范. 官网 : https://swagger.io/ 准备工作 pom.xml jar引入: <swagger.version>2.9.2</swagger.version> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swag

SpringBoot整合Swagger测试api构建

@Author:SimpleWu 什么是Swagger? Swagger是什么:THE WORLD'S MOST POPULAR API TOOLING 根据官网的介绍: Swagger Inspector:测试API和生成OpenAPI的开发工具.Swagger Inspector的建立是为了解决开发者的三个主要目标. 执行简单的API测试 生成OpenAPI文档 探索新的API功能 我的理解Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.简单

SpringBoot整合swagger

现在Web项目前后端分离越来越多,前后端的沟通成本成了头大的难题. 上个项目虽然使用Postman已经降低了不少沟通成本,但是还是要手写不少Api到Postman测试,耗费了不少时间.这次新项目决定使用SpringBoot来做,各方面都节省了不少配置,一想到Api的对接就有点头大,于是决定把Swagger集成进来,实现Api文档的自动生成(通过http://localhost:8080/swagger-ui.html直接访问),这样前后端对接基本上就零成本了. 话不多说,搞起. 首先,pom引入

怎样获取从服务器返回的xml或html文档对象

使用 xhr.responseXML;  通过这个属性正常获取XML或HTML文档对象有两个前置条件: 1. Content-Type头信息的值等于: text/xml 或 application/xml 2. xhr.responseType 需要赋值为: "document" var xhr = new XMLHttpRequest(); xhr.open('GET', '/server', true); xhr.responseType = 'document'; xhr.ove

告别手写接口文档时代,比Swagger功能更强大的LKADocument接口文档管理框架诞生了!

更详细的更全面的教程请观看作者亲自录制的视频教程,地址: https://edu.51cto.com/sd/9cb7fLKADocument视频教程 一.介绍 在前后端分离,分工更加明细化的今天,为了减少前端和后台开发人员的沟通成本,能够让他们做到并行开发,同时也能保证前端和后端开发人员所看到的接口文档的一致性,即时性,以此来大大提高工作效率.所以出现了一些非常优秀的接口管理工具,具有代表性的像Swagger,因为它能够通过注解或yml和JSON描述文件来自动生成接口文档.但是我觉得它不管是在配

使用Swagger 搭建高可读性ASP.Net WebApi文档

一.前言 在最近一个商城项目中,使用WebApi搭建API项目.但开发过程中,前后端工程师对于沟通接口的使用,是非常耗时的.之前也有用过Swagger构建WebApi文档,但是API文档的可读性并不高.尤其是没有传入参数和传出结果的说明,导致开发人员沟通困难.在园子里看到一篇关于对Swagger优化的文章,有很大的改进.解决了传入参数,API分区域筛选等问题, 非常感谢博主简玄冰. 不过实践之后,发现还有些问题未解决: 接口返回的对象,没有汉化说明 接口授权参数(token)未统一传入 所以,决

详解xml文件描述,读取方法以及将对象存放到xml文档中,并按照指定的特征寻找的方案

主要的几个功能: 1.完成多条Emp信息的XML描述2.读取XML文档解析Emp信息3.将Emp(存放在List中)对象转换为XML文档4.在XML文档中查找指定特征的Emp信息 dom4j,jaxen 官网下载页面: http://sourceforge.net/projects/dom4j/files/dom4j-2.0.0-ALPHA-2/ 也可以在网盘上面下载:http://yunpan.cn/cwaNde7UYN83d  提取码 e247 1 完成多条Emp信息的XML描述 1.1 问

Spring Boot2 系列教程(十七)SpringBoot 整合 Swagger2

前后端分离后,维护接口文档基本上是必不可少的工作. 一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理想的状态,实际开发中却很少遇到这样的情况,接口总是在不断的变化之中,有变化就要去维护,做过的小伙伴都知道这件事有多么头大!还好,有一些工具可以减轻我们的工作量,Swagger2 就是其中之一,至于其他类似功能但是却收费的软件,这里就不做过多介绍了.本文主要和大伙来聊下 在Spring Boot 中如何整合 Swagger

SpringBoot集成Swagger,Postman,newman,jenkins自动化测试.

环境:Spring Boot,Swagger,gradle,Postman,newman,jenkins SpringBoot环境搭建. Swagger简介 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件. 一.SpringBoot集成Swagger 1.build.gradle增加swagger相关jar包,maven项目同理. 2.增加SwaggerConfig配置文件. 前两步完成,访问http://localhost:8080/demoService/swa