如何解决 ApiPlatform 中实体未显示在 Swagger UI 的问题-php教程-PHP中文网

如何解决 ApiPlatform 中实体未显示在 Swagger UI 的问题

在 Symfony 5.4 + ApiPlatform 环境中，自定义 Entity 无法出现在 Swagger UI 文档页面，通常是因使用了已废弃的注解命名空间 ApiPlatform\Core\Annotation\ApiResource，需升级为 ApiPlatform\Metadata\ApiResource。

在 symfony 5.4 + apiplatform 环境中，自定义 entity 无法出现在 swagger ui 文档页面，通常是因使用了已废弃的注解命名空间 `apiplatform\core\annotation\apiresource`，需升级为 `apiplatform\metadata\apiresource`。

ApiPlatform 自 3.0 版本起全面迁移至新的元数据系统（ApiPlatform\Metadata），旧版 ApiPlatform\Core\Annotation 已被弃用且不再被自动识别。即使你已正确添加 @ApiResource()、清除缓存（bin/console cache:clear）并重启开发服务器，若注解导入路径错误，该实体仍不会被 API Platform 扫描和注册，导致其完全不出现在 OpenAPI 文档（Swagger UI）中。

✅ 正确做法是更新命名空间导入：

// api/src/Entity/Review.php
<?php namespace App\Entity;

use ApiPlatform\Metadata\ApiResource; // ✅ 替换为新命名空间
use Doctrine\ORM\Mapping as ORM;

#[ApiResource] // 推荐使用 PHP 8+ 属性语法（Attribute）
class Review
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: 'integer')]
    private ?int $id = null;

    #[ORM\Column(type: 'integer')]
    public int $rating = 0;

    #[ORM\Column(type: 'text')]
    public string $body = '';

    #[ORM\Column(type: 'string', length: 255)]
    public string $author = '';

    #[ORM\Column(type: 'datetime_immutable', nullable: true)]
    public ?\DateTimeInterface $publicationDate = null;

    #[ORM\ManyToOne(targetEntity: Book::class)]
    public ?Book $book = null;

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

⚠️ 注意事项：

若项目仍在使用 PHP 必须使用 use ApiPlatform\Metadata\ApiResource;
确保实体类位于 src/Entity/（或 api/src/Entity/）且被 Doctrine 实体扫描器覆盖（检查 doctrine.orm.mappings 配置）
运行 bin/console debug:router | grep api 和 bin/console api:openapi:export 可验证实体是否已被注册
若依赖 Book 类，请确保 App\Entity\Book 同样使用 ApiPlatform\Metadata\ApiResource 并已正确定义

? 总结：从 ApiPlatform v3 开始，ApiResource 必须从 ApiPlatform\Metadata 导入；沿用旧命名空间将导致实体静默失效——这是新手最常见的“文档不显示”原因。升级后无需额外配置，刷新 Swagger UI 即可立即看到 /api/reviews 等端点。