Swagger-core: 模型访问器上的 ArraySchema 注释未正确映射到 API 规范

我将 swagger-core 2.0.0 与 Jackson 2.9.4 和 Jersey 2.26 一起使用。

我会开始说我正在边做边学，所以我可能做错了。 如果是这样，请指出我正确的方向。 但我想我发现了一个..设计限制？ 这个问题的基本要点是我没有成功通过注释利用 OAS 功能，我认为这是注释实现的限制。

考虑一个模型对象：

public class ExampleModel {
  private String[] stringArray;

  @ArraySchema(
    schema = @Schema(
        description = "Hello, World!",
        example = "Lorem ipsum dolor set"
    )
  )
  public void setStringArray(String[] value) { stringArray = value; }
  public String[] getStringArray() { return stringArray; }
}

生成的 openapi.json 片段最终看起来像：

"components": {
  "schemas": {
    "ExampleModel": {
      "type": "object",
      "properties": {
        "stringArray": {
          "type": "array",
          "description": "Hello, World!",
          "example":"Lorem ipsum dolor set"
          "items": {
            "type": "string",
            "description": "Hello, World!"
          }
        }
      }
    }
  }
}

这个输出有两个问题：

1. 请注意，数组元素中的描述字段也会为数组本身发出。 这在 Swagger UI 处理时会导致一些难看的冗余，并且无法将数组的描述与元素分开指定。
2. 示例字段已完全损坏。 @Schema注释不支持示例字段的数组，这与规范冲突。 手动编写的 JSON/YAML允许这样做（向下滚动到“数组示例”部分）。

如果你尝试像@Schema(example = "[ \"example 1\",\"example2\"]")这样的东西，你最终会得到一个 JSON 数组的字符串表示，而不是一个实际的数组。 因此，总而言之，没有（明显的）方法可以通过注释指定数组示例。

我想要的输出是这样的：

"components": {
  "schemas": {
    "ExampleModel": {
      "type": "object",
      "properties": {
        "stringArray": {
          "type": "array",
          "description": "An array of lorem ipsum dolor set",
          "example": [ "Lorem", "ipsum", "dolor", "set" ],
          "items": {
            "type": "string",
            "description": "Hello, World!"
          }
        }
      }
    }
  }
}

我希望这将涉及向@ArraySchema添加“描述”和字符串 [] 示例字段，因此生成上述内容的注释可能如下所示：

@ArraySchema(
    description = "An array of lorem ipsum dolor set",
    example = {"Lorem", "ipsum", "dolor", "set"},
    schema = @Schema(
        description = "Hello, World!"
    )
)