ApiPlatform 3.1自定义Action中DTO数组Swagger文档自动生成问题

1. 给DTO属性加显式类型+正确的@var注释 #

ApiPlatform的OpenAPI生成依赖PHP类型提示，光写@var注释没用，必须给属性加上array类型声明，同时@var里要明确标注数组元素的具体DTO类：

class YourResponseDto
{
    /**
     * @var InputDto[]
     */
    public array $inputs;

    /**
     * @var OutputDto[]
     */
    public array $outputs;
}

别只写@var array，必须指定具体的DTO类名，不然生成器只会默认识别成string[]。

2. 给子DTO加ApiSchema注解 #

如果你的InputDto、OutputDto不是实体类，ApiPlatform可能不会把它们当成可识别的API模型，直接给这些子DTO添加#[ApiSchema]注解：

use ApiPlatform\Metadata\ApiSchema;

#[ApiSchema(title: "InputDto", description: "输入数据结构")]
class InputDto
{
    public string $field1;
    public int $field2;
}

#[ApiSchema(title: "OutputDto", description: "输出数据结构")]
class OutputDto
{
    public string $result;
    public bool $success;
}

要是这些DTO本身就是API资源，加#[ApiResource]也可以，但单纯为了生成文档的话，ApiSchema足够。

3. 自定义Action里明确指定输出类型 #

在自定义Action的#[ApiResource]注解中，通过output参数明确指定返回的响应DTO类，同时配置正确的序列化组：

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/custom-action',
            provider: YourCustomProvider::class,
            output: YourResponseDto::class,
            normalizationContext: ['groups' => ['response:read']]
        )
    ]
)]
class YourCustomAction
{
    // 空类即可，无需额外逻辑
}

然后在响应DTO的属性上添加对应的序列化组注解：

use Symfony\Component\Serializer\Annotation\Groups;

class YourResponseDto
{
    /**
     * @var InputDto[]
     */
    #[Groups(['response:read'])]
    public array $inputs;

    /**
     * @var OutputDto[]
     */
    #[Groups(['response:read'])]
    public array $outputs;
}

4. 清除缓存并刷新文档 #

ApiPlatform会缓存OpenAPI的元数据，修改注解后必须清除Symfony缓存：

php bin/console cache:clear

之后重新访问Swagger UI页面，检查数组类型是否已更新为正确的DTO结构。

5. 检查DTO的自动加载配置 #

确保你的DTO类放在Composer自动加载覆盖的目录下（比如src/Dto/），同时composer.json中的自动加载规则正确：

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

如果类没有被正确加载，ApiPlatform无法解析它的结构，自然会识别错误类型。

内容的提问来源于stack exchange，提问作者viko