NelmioApiDocBundle需显式添加@OA注解（如@OA\Get）才能生成文档，不识别#[Route]；ApiPlatform则依赖#[ApiResource]标记实体，不扫描控制器。
直接用 NelmioApiDocBundle 或 ApiPlatform，别自己手写 OpenAPI YAML —— 前者适合已有 Symfony 项目快速加文档，后者更适合从零建 API 服务。两者都支持 PHP 8.0+ Attribute 注解，但行为逻辑和配置粒度差异很大，选错会卡在路由扫描或模型推导上。
用 NelmioApiDocBundle 扫描控制器时，路由必须显式声明
NelmioApiDocBundle 默认不读取 #[Route] 的 path 和 methods，它依赖注解中的 @OA\Get、@OA\Post 等 OpenAPI 原生注解来识别接口。如果你只写了路由属性而没写 @OA\*，生成的文档里就啥也没有。
- 必须在控制器方法上加
@OA\Get(path="/api/users")这类完整路径定义，不能只靠#[Route('/api/users')] - 若想复用路由定义，得手动把
#[Route]的path和methods拷进@OA\*注解里，否则nelmio_api_doc不认 -
config/packages/nelmio_api_doc.yaml中的areas.path_patterns只控制扫描范围，不自动提取路由信息
ApiPlatform 自动生成文档的前提是实体类被标记为 API 资源
ApiPlatform 的文档生成完全基于资源（#[ApiResource]）而非控制器。它不看 Controller 文件，只扫描带 #[ApiResource] 的实体类或 DTO，然后根据 collectionOperations 和 itemOperations 推出端点。
- 哪怕你写了完整的
UserController，只要User实体没加#[ApiResource]，/api/users就不会出现在文档里 -
api_platform.resources配置项在api_platform.yaml中只是开关，真正触发文档生成的是类上的属性 - 如果用了自定义控制器（如
controller: App\Controller\UserCustomController），必须在#[ApiResource]中显式指定，否则默认控制器逻辑会被绕过
OpenAPI Schema 推导失败常因类型反射缺失
两种工具都会尝试从 PHP 类型声明或 DocBlock 中推导请求/响应结构，但一旦遇到模糊类型（比如 array、mixed、未声明返回类型的 public function），就会生成空 schema 或报 Unable to guess type 警告。
- 在控制器方法参数上用
#[MapRequestPayload]（Nelmio）或#[RequestBody]（ApiPlatform）比仅靠类型声明更可靠 - DTO 类必须有明确的属性类型（
public string $name;）或@var注解，否则items、properties字段为空 -
#[Model(name: "UserResponse")]这类显式模型命名能绕过自动推导失败，尤其在同名类跨 namespace 时必加
Swagger UI 路径 404 的真实原因往往是路由未启用或权限拦截
生成文档文件（swagger.json）成功 ≠ 能通过 HTTP 访问。常见问题不是配置错，而是 Symfony 路由层根本没放行该路径。
-
NelmioApiDocBundle默认注册^/api/doc路由，但若项目启用了security.firewalls.main.access_control，需确保该路径被排除，例如加- { path: ^/api/doc, roles: IS_AUTHENTICATED_ANONYMOUSLY } -
ApiPlatform的/api/docs是由api_platform.swagger.normalizer服务动态生成的，如果api_platform.swagger.enabled: true没开，页面空白且无报错 - 使用
symfony/web-server-bundle本地调试时，某些 CLI 启动方式不加载全部路由缓存，重启cache:clear+server:restart才生效
最易被忽略的一点：Nelmio 和 ApiPlatform 对 #[OA\Property] 的处理逻辑不同 —— Nelmio 会合并注解与属性类型，ApiPlatform 则优先信任注解。如果你混用两者生成同一份文档，required 字段可能在一处出现、另一处消失。
