如何解决 ApiPlatform 中实体未显示在 Swagger UI 的问题
在 Symfony 5.4 与 ApiPlatform 集成开发时，自定义的实体类若未出现在 Swagger UI 文档中，通常是由于使用了已过时的注解命名空间ApiPlatform\Core\Annotation\ApiResource。解决方案是将其更新为新的命名空间ApiPlatform\Metadata\ApiResource。
当你在 Symfony 5.4 项目中集成 ApiPlatform 时，是否遇到过这样的困扰：已经定义了一个实体类，但在 Swagger UI 接口文档页面却始终找不到它的 API 端点？这通常不是一个复杂的配置问题，而是一个由版本升级引发的常见误区。
导致此问题的核心原因，往往是实体类顶部导入了一个已被废弃的注解命名空间：ApiPlatform\Core\Annotation\ApiResource。自 ApiPlatform 3.0 版本起，框架引入了全新的元数据系统，并迁移至 ApiPlatform\Metadata 命名空间。旧的 ApiPlatform\Core\Annotation 命名空间已被标记为弃用，其下的注解将不再被框架的自动发现机制所识别。
这意味着，即使你为实体添加了 @ApiResource 注解，并执行了缓存清理（bin/console cache:clear）和服务器重启，只要导入的命名空间是错误的，该实体就会被 ApiPlatform 的资源扫描器“静默过滤”。最终结果是，该实体既不会生成对应的 REST API 路由，也无法在 OpenAPI 规范（即 Swagger UI 所展示的内容）中呈现。
✅ 正确做法是更新命名空间导入
解决方法非常明确：将实体类文件中的命名空间导入语句更新为正确的路径。以下是修改后的代码示例：
// api/src/Entity/Review.php
id;
}
}
⚠️ 注意事项
- 若你的项目仍在使用 PHP 8.0 以下版本，无法采用属性语法，则需继续使用注解语法（例如
/** @ApiResource */）。但务必确保顶部的use语句指向ApiPlatform\Metadata\ApiResource。 - 请确认实体类位于正确的目录下，通常是
src/Entity/或api/src/Entity/，并且该路径已被 Doctrine ORM 的实体映射配置（可检查config/packages/doctrine.yaml中的mappings设置）所包含。 - 有两个实用的命令行工具可用于验证实体是否成功注册：执行
bin/console debug:router | grep api可以筛选出所有生成的 API 路由；执行bin/console api:openapi:export可以导出完整的 OpenAPI 规范，检查其中是否包含你的实体定义。 - 如果实体类中存在关联关系（如示例中的
Book），请确保关联的实体类（App\Entity\Book）也同样正确使用了ApiPlatform\Metadata\ApiResource并已正确定义。
? 总结
简而言之，从 ApiPlatform v3 版本开始，ApiResource 注解或属性必须从 ApiPlatform\Metadata 命名空间导入。继续使用旧的命名空间会导致实体在文档中“隐形”，这是开发者在升级或集成 ApiPlatform 时，遇到“Swagger UI 不显示实体”问题的最常见原因。完成这一关键的命名空间修正后，通常无需额外配置，只需刷新 Swagger UI 页面，你就能立即在文档中看到对应的 API 端点（例如 /api/reviews）了。
