apimodelproperty爆红_swagger中@ApiModelProperty中example属性对List的支持

最新推荐文章于 2023-12-21 17:22:50 发布

295515812

最新推荐文章于 2023-12-21 17:22:50 发布

阅读量1.5k

点赞数

文章标签： apimodelproperty爆红

本文链接：https://blog.csdn.net/weixin_33603429/article/details/113891054

版权

本文讨论了在Swagger中使用@ApiModelProperty注解时，example属性对List类型支持不佳的问题，并介绍了现有版本的限制及预计在3.0.0版本中的改进。同时，提供了一种通过设置allowableValues临时解决的方法，展示了如何在Swagger UI中正确渲染List类型的示例。

摘要由CSDN通过智能技术生成

swagger中@ApiModelProperty注解example使用问题

example属性默认是String的, 对应List的支持不好

@ApiModelProperty(position = 2, example = "PRD1, PRD2, PRD3")

// This generates -> "productIdentifiers": "PRD1, PRD2, PRD3" // Its not json array

@ApiModelProperty(position = 2, example = "["PRD1", "PRD2", "PRD3"]")

// This generates -> "productIdentifiers": "["PRD1", "PRD2", "PRD3"]" // Its too not json array

@ApiModelProperty(position = 2, dataType="List", example = "PRD1, PRD2, PRD3")

private List productIdentifiers;

//This generates -> `"productIdentifiers": "PRD1, PRD2, PRD3"`

@ApiModelProperty(position = 2, dataType="java.util.List", example = "PRD1, PRD2, PRD3")

// This generates -> "productIdentifiers": "PRD1, PRD2, PRD3"

@ApiModelProperty(position = 2, dataType="String[]", example = "PRD1, PRD2, PRD3")

// This generates -> "productIdentifiers": "PRD1, PRD2, PRD3"

依赖版本

io.springfox

springfox-swagger2

2.7.0

暂时还没有适配

TLDR: One of the contributers on Swagger-API has worked on this functionality to add this in version 3.0.0 but it's not sure yet when this will be released. For now it stands on the feature/3.0.0-rc2 branch at the Swagger-API GitHub

I've been working with Swagger for almost two months now and as our project progressed issues like this showed up. Now I did some research and read on the GitHub pages for the Swagger-API that this feature simply doesn't work (yet).

As described here and [here would be an other link but my reputation is not high enough to post more than 2 links] this feature has been requested several times since August 2015 with not much luck.

Now on this issue on the Swagger-API github, one of the contributors commented:

This takes a major refactoring of the models, which is on the way. 3 March 2017

which lead to a later comment:

Will be supported in 3.0.0 support, please see the feature/3.0.0-rc2 branch for details. 27 June 2017

And on 9 August 2017 someone asked when the release of version 3.0.0 would be with no further response.

So in conclusion, support for examples for arrays/Lists has been worked on and should be available in version 3.0.0 but no more news on when that would be released.

取巧的解决方法

# 此方法只能显示一个

public class MajorNutrientElements {

@ApiModelProperty(name = "majorName", value = "食材名称", example = "西红柿", required = true)

private String majorName;

@ApiModelProperty(name = "nutrientElements", value = "食材对应的营养元素", allowableValues = "维生素E", required = true)

private List nutrientElements;

}

swagger中显示

{

"majorName": "西红柿",

"nutrientElements": [