swagger-php 使用属性响应对象数组

Question

刚刚学习使用属性来描述函数参数和响应。我正在尝试描述一个返回对象数组的响应对象，但到目前为止使用数组的运气并不好，这就是我现在所拥有的，它返回一个对象，我希望它是一个对象数组:

#[OA\Response(
    response: 201,
    description: "Get the list",
    content: new OA\JsonContent(
        properties: [
            new OA\Property(
                property: "property name 1",
                type: "string",
                example: "value 1"
            ),
            new OA\Property(
                property: "property name 2",
                type: "string",
                example: "value 2"
            )
        ],
        type: 'object'
    )
)]

任何指导将不胜感激！

Answer 1

一种典型的方法是使用对象模式的引用（如果有）。 例如，类似 https://github.com/zircote/swagger-php/blob/master/Examples/using-links-php81/RepositoriesController.php#L16

如果您喜欢内联对象属性，它应该与此类似（未经测试）：

<?php

use OpenApi\Attributes as OA;

#[OA\Get(path: '/api/get')]
#[OA\Response(
    response: 201,
    description: "Get the list",
    content: new OA\JsonContent(
        type: 'array',
        items: new OA\Items(
        // your list item
            type: 'object',
            properties: [
                new OA\Property(
                    property: "property name 1",
                    type: "string",
                    example: "value 1"
                ),
                new OA\Property(
                    property: "property name 2",
                    type: "string",
                    example: "value 2"
                )
            ]
        )
    )
)]
class Controller
{
}

Answer 2

假设一个对象是一个单独的类，具有自己的 Open API 模式，您可以如下所示声明它：

#[OA\Property(
        type: 'array',
        items: new OA\Items(
            oneOf: [
                new OA\Schema(ref: '#/components/schemas/CarsResult'),
                new OA\Schema(ref: '#/components/schemas/TrucksResult'),
            ]
        ),
        nullable: false
    )]