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
源码地址
原文地址: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