如何修复zircote/swagger-php中@OA\Items()父类型必须为array的警告？

API 探路者

2026-8-16

问题原因及解决思路

核心原因

@OA\Items() 注解的作用是定义数组类型属性的元素结构，它的父级属性必须声明为 type="array"。你代码里多处把它用在了 type="object" 的属性下，这就触发了警告。

具体代码修正点

1. 修正`data`属性的注解

你的data属性类型是object，但错误嵌套了@OA\Items()，应该直接用@OA\Property定义对象的字段：

@OA\Property(
    property="data",
    type="object",
    // 移除@OA\Items()，直接嵌套@OA\Property定义对象字段
    @OA\Property(
        property="organization",
        type="string",
        example="1"
    ),
    @OA\Property(
        property="site",
        type="string",
        example="1"
    ),
    // ... 其他data的字段属性
    @OA\Property(
        property="tasks",
        type="object"
        // 移除多余的@OA\Items()
    ),
    @OA\Property(
        property="files",
        type="object"
        // 移除多余的@OA\Items()
    ),
    @OA\Property(
        property="notes",
        type="object"
        // 移除多余的@OA\Items()
    ),
),

2. 修正`tasks`/`files`/`notes`的注解

如果这三个字段实际是数组类型（比如存储多个任务、文件），需要把它们的type改成array，再保留@OA\Items()并定义数组元素结构：

@OA\Property(
    property="tasks",
    type="array",
    @OA\Items(
        @OA\Schema(
            // 定义单个task的结构，示例：
            @OA\Property(property="id", type="string"),
            @OA\Property(property="name", type="string")
        )
    )
),

如果它们确实是对象类型，直接删除@OA\Items()即可。