Api Platform v3添加#[ApiResource]实体触发类型错误求助

问题场景 #

从零开始通过 Symfony CLI 安装 Api Platform v3，生成 Test 实体并添加 #[ApiResource] 属性后，抛出以下错误：

ApiPlatform\Metadata\ApiResource::withDescription(): Argument #1 ($description) must be of type string, null given, called in /var/www/api_v3/vendor/api-platform/core/src/Metadata/Resource/Factory/OperationDefaultsTrait.php on line 58

环境配置：Debian 11、PHP 8.1、Apache，Symfony 6.1。相关代码如下：

Test 实体代码 #

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use App\Repository\TestRepository;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity(repositoryClass: TestRepository::class)]
#[ApiResource]
class Test
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    public function getId(): ?int
    {
        return $this->id;
    }
}

composer.json #

{
    "type": "project",
    "license": "proprietary",
    "minimum-stability": "stable",
    "prefer-stable": true,
    "require": {
        "php": ">=8.1",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "api-platform/core": "^3.0",
        "doctrine/annotations": "^1.0",
        "doctrine/doctrine-bundle": "^2.7",
        "doctrine/doctrine-migrations-bundle": "^3.2",
        "doctrine/orm": "^2.13",
        "nelmio/cors-bundle": "^2.2",
        "phpdocumentor/reflection-docblock": "^5.3",
        "phpstan/phpdoc-parser": "^1.13",
        "symfony/apache-pack": "^1.0",
        "symfony/asset": "6.1.*",
        "symfony/console": "6.1.*",
        "symfony/dotenv": "6.1.*",
        "symfony/expression-language": "6.1.*",
        "symfony/flex": "^2",
        "symfony/framework-bundle": "6.1.*",
        "symfony/property-access": "6.1.*",
        "symfony/property-info": "6.1.*",
        "symfony/proxy-manager-bridge": "6.1.*",
        "symfony/runtime": "6.1.*",
        "symfony/security-bundle": "6.1.*",
        "symfony/serializer": "6.1.*",
        "symfony/twig-bundle": "6.1.*",
        "symfony/validator": "6.1.*",
        "symfony/yaml": "6.1.*"
    },
    "config": {
        "allow-plugins": {
            "composer/package-versions-deprecated": true,
            "symfony/flex": true,
            "symfony/runtime": true
        },
        "optimize-autoloader": true,
        "preferred-install": {
            "*": "dist"
        },
        "sort-packages": true
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "App\\Tests\\": "tests/"
        }
    },
    "replace": {
        "symfony/polyfill-ctype": "*",
        "symfony/polyfill-iconv": "*",
        "symfony/polyfill-php72": "*",
        "symfony/polyfill-php73": "*",
        "symfony/polyfill-php74": "*",
        "symfony/polyfill-php80": "*",
        "symfony/polyfill-php81": "*"
    },
    "scripts": {
        "auto-scripts": {
            "cache:clear": "symfony-cmd",
            "assets:install %PUBLIC_DIR%": "symfony-cmd"
        },
        "post-install-cmd": [
            "@auto-scripts"
        ],
        "post-update-cmd": [
            "@auto-scripts"
        ]
    },
    "conflict": {
        "symfony/symfony": "*"
    },
    "extra": {
        "symfony": {
            "allow-contrib": false,
            "require": "6.1.*"
        }
    },
    "require-dev": {
        "symfony/maker-bundle": "^1.47"
    }
}

解决方案 #

方案1：升级 Api Platform 核心包 #

这是 Api Platform 3.0 早期版本的已知 bug，在 3.0.12 版本中已修复。执行以下命令升级：

composer require api-platform/core:^3.0.12

升级完成后清除缓存：

symfony console cache:clear

方案2：临时手动添加 description 属性 #

如果暂时无法升级，给 #[ApiResource] 添加 description 参数，避免 null 值传入：

#[ApiResource(description: 'Test entity')]

原因说明 #

报错根源在于 Api Platform 自动生成操作描述时，会尝试从实体的 PHPDoc 注释中提取内容。如果实体没有编写 PHPDoc 注释，早期 3.0 版本会返回 null，而 withDescription() 方法要求参数必须是字符串类型，因此触发类型错误。3.0.12 版本修复了这个问题，当没有 PHPDoc 时会使用默认的空字符串或实体类名作为描述。

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