Question

在Java / Spring项目中，我们使用Swagger-Ui自动记录我们的REST-API。
最近，我继续尝试确保所有API的文档正确，发现对于某些端点，方法参数的JSON结构很奇怪。

在项目中，我们有一个类型为“ SerialNo”的类型，它基本上是一个特定范围（10000000-39999999）内的整数。

内部，我们使用Jackson来对对象进行序列化和反序列化（例如，用于事件代理），并且我们将其设置为在JSON文档中SerialNumber看起来像是整数

// Product
{
  "header": { // type: ProductHeader
    "serialNo": 17654321
    ...
  }
  "wildly": {
    "nested": {
      "and": "grown"
      "structures": 12
    }
  }
}

这也是REST-Call期望的结构。

现在Swagger-Ui以此为例：

// Product
{
  "header": {
    "serialNo": {} // <--- This is missleading
    ...
  }
  "wildly": {
    "nested": {
      "and": "grown"
      "structures": 12
    }
  }
}

我发现我可以provide an example for the param that takes this structure by using @ApiParam(example = "...")，但是由于结构已经变大，我不觉得这是可以满足的，所以SerialNo也将出现在多个结构中，我认为提供此代码很可笑且容易出错API文档中每次出现的示例。

我将@ApiParam引向ProductHeader中的对象"header":中的字段

@Getter
@Setter
public class ProductHeader {
   @JsonProperty
   @ApiParam(example = "17654321") private SerialNo serialNo;
   // ...
}

但这不会改变任何事情。

是否有可能使用swaggers文档的生成功能来获得正确的示例输出，而不必每次都提供完整结构的示例？

修复Swagger-Ui的JSON示例-显示JsonNumber而不是对象

0 个答案: