ApiPlatform适合新项目从零建模或老项目可重构为“资源即实体”结构的场景；不适合已有大量#[Route]控制器的项目，此时应选NelmioApiDocBundle。
ApiPlatform 适合什么项目结构
ApiPlatform 不是“加个包就能用”的工具，它默认只扫描带 #[ApiResource] 的类，完全跳过 Controller。如果你已有大量基于 #[Route] 的控制器，硬套 ApiPlatform 反而要重写路由、权限、序列化逻辑——这时候该选 NelmioApiDocBundle。ApiPlatform 真正省力的场景是：新项目从零建模，或老项目能重构为“资源即实体”的结构（比如 User、Post、Invoice 这类有明确生命周期和标准操作的对象）。
启用 Swagger UI 却打不开 /api/docs
常见原因不是代码写错，而是配置链断在环境或路由层面：
- 检查
config/packages/api_platform.yaml是否启用了enable_swagger_ui: true和enable_swagger: true； - 确认你访问的是
/api/docs（不是/docs或/swagger），且当前环境是dev（prod 下默认禁用 UI）； - Docker 或 Nginx 用户注意：如果用了
try_files $uri /index.php?$query_string类规则，可能把/api/docs当静态路径拦截了，需显式放行以/api/开头的请求。
返回数据字段为空或结构不对
ApiPlatform 默认靠 Doctrine 类型 + PHPDoc + 校验注解推导字段，但推导失败时不会报错，只会静默忽略：
- 确保实体属性有类型声明（如
public ?string $name = null;），PHP 8.1+ 的联合类型（string|null）也能识别； - 用
#[Groups]控制序列化范围，例如#[Groups(['read'])]配合 API 资源的normalizationContext； - 想补文档描述？在属性 PHPDoc 里加
@OA\Property(description="用户邮箱")，不是写在类顶部； - 如果返回空数组，先确认是否漏了
#[ApiResource]，再查GET操作是否被collectionOperations显式禁用（默认开启）。
需要自定义非 CRUD 路由（比如 /invoices/{id}/document）
别试图在 #[ApiResource] 里硬塞 PDF 路由——它不处理非 RESTful 行为。正确做法是分两层：
- 在实体中加一个只读方法，比如
getUrl(): string，用#[Groups]暴露给 API 响应； - 另写一个传统 Symfony 控制器，绑定
#[Route('/invoices/{id}/document', name: 'invoice_document')]，在里面调用 PDF 生成服务； - 关键点：这个控制器不在 ApiPlatform 管理范围内，所以权限、缓存、日志都得自己配，别指望
security配置块自动生效。
#[ApiResource] 上堆逻辑。 
