php - @ApiProperty openapi_context 类型数组示例

Question

是否可以为@ApiProperty 创建 openapi_context "type"="array"？使用注释编写此类数组的“示例”值的正确方法是什么？我正在使用 OAS3

/**
 * @ApiProperty(
 *     attributes={
 *      "openapi_context"={
 *        "type"="array",
 *        "example"="array example goes here"
 *      }
 *     }
 * )
 *
 * @var array<array>
 */

编辑:

预期输出(当我在 SwaggerUI 中将它输入到请求正文时有效)是

    "my_array": {
      "key" : {
        "key1" : "value 1",
        "key2" : "value 2",
        "key3" : "value 3"
       }
     }

那里没有方括号

Answer 1

我不确定是否理解您的问题，因为我不知道您的数组的内容。如果这不能回答您的问题，请随时添加评论。

数组类型

OpenApi Specification 定义的原始数据类型记录在 this chapter 中.没有提到数组，当然是因为这不是原始数据类型。

因为，如果你看看 schema 3.0 , Line 203模式描述开始。接受数组 ( Line 263 )。
所以，是的，可以为 @ApiProperty 创建 openapi_context "type"="array"

示例
如果你看看 schema 3.0 , Example ( Line 323 ) 是没有规范的对象。所以你可以写你想要的。我不是一个大粉丝，很多文档都使用示例来提供可接受的值。

所以，我使用尊重 OAS3 的 Swagger。数组是 documented你可以在评论中找到一些例子。有些例子在“评论”中定义。这些示例来自 Swagger 文档。

整数数组的示例 "[ 1, 2, 3, 4 ]"

对象数组的示例 "[ {"id": 5}, {"id": 8} ]"

整数数组的数组示例 "[ [1, 2], [3, 4] ]"

等

对于多维数组，这是 swagger 上下文:

    # [ [1, 2], [3, 4] ]
    type: array
    items:
      type: array
      items:
        type: integer

注释是:

    /**
     * @ApiProperty(
     *     attributes={
     *      "openapi_context"={
     *        "type"="array",
     *        "items" = {"type"="array", "items"={"type"={"integer","string"}}},
     *        "example"="[[1,'foo'], ['bar',4, 5]]"
     *      }
     *     }
     * )
     * @ORM\Column(type="array")
     */

我创建了一个具有属性的实体，该属性是一个包含字符串或整数的多维数组。 ((字符串或整数)数组的数组)，我截取了 swagger 文档的屏幕截图。好像没问题!

样本的结果是:



生成的架构是:



The example are well documented ，你可以为你的数组找到答案。