Symfony API文档生成首选NelmioApiDocBundle（适配现有控制器）或ApiPlatform（适配资源驱动新项目）；前者依赖@OA注解手动声明接口，后者通过#[ApiResource]自动推导CRUD文档。
Symfony 项目里生成 API 文档，核心不是写文档，而是让工具从代码里“读懂”接口——Swagger 和 OpenAPI 是描述标准，NelmioApiDocBundle 和 ApiPlatform 是两条主流自动化路径。选哪个，取决于你项目当前结构和控制粒度需求。
用 NelmioApiDocBundle（适合已有控制器的项目）
它直接读控制器里的 @OA\Get、@OA\Post 这类 OpenAPI 注解，不依赖路由定义本身。也就是说，即使你用了 #[Route]，也得手动把路径、方法、参数再写一遍进 @OA\* 里，否则文档为空。
- 安装：
composer require nelmio/api-doc-bundle - 配置
config/packages/nelmio_api_doc.yaml，重点设好areas.path_patterns，比如- ^/api(?!/doc$)排除文档自身路由 - 在控制器方法上加完整注解，例如：
/** @OA\Get(path="/api/users", summary="获取用户列表") */ - 响应结构要显式声明，比如用
@OA\JsonContent(@OA\Items(ref="#/components/schemas/User"))，否则可能推导失败
用 ApiPlatform（适合以资源为中心的新建或重构项目）
它完全不看 Controller，只扫描带 #[ApiResource] 的实体类或 DTO。一旦标记，标准 CRUD 路由自动注册，文档也自动生成。想改行为，就调 collectionOperations 或 itemOperations。
- 确保
config/packages/api_platform.yaml中启用了：enable_swagger: true和enable_swagger_ui: true - 在实体类顶部加
#[ApiResource]，如#[ApiResource]class User { ... } - 访问
/api/docs（注意不是/docs或/swagger），开发环境默认可用 - 字段说明靠 Doctrine 类型 +
#[Assert\NotBlank]等自动推导；想补描述，用 PHPDoc +@OA\Property
常见卡点与绕过方法
文档生成成功但页面 404，大概率是环境或配置链断了，不是代码问题。
- 运行的是
prod环境？先执行php bin/console cache:warmup --env=prod，否则注解不解析 - Swagger UI 打不开？检查是否漏了
enable_swagger_ui: true，且路径没被 Nginx/Apache 的try_files规则拦截 - 返回结构为空？别只写
public function index(): JsonResponse，加上#[MapRequestPayload]（Nelmio）或明确 DTO 类型（ApiPlatform），或用#[Model(name: "UserResponse")]指定模型 - 不想手写重复路径？可封装一个 PHP 脚本，从
#[Route]属性中提取 path/methods，自动注入到对应@OA\*注解里，但需谨慎维护
生成后怎么用
文档本质是符合 OpenAPI 3.0 规范的 JSON/YAML 文件，/api/doc（Nelmio）或 /api/docs（ApiPlatform）只是前端 UI 入口。你还可以：
- 把
swagger.json提交给第三方测试工具（如 Postman、Hoppscotch）做接口调试 - 用 Swagger Codegen 根据该文件反向生成客户端 SDK 或服务端骨架
- 集成进 CI 流程：每次提交后跑命令生成文档快照，对比变更，防止接口改了但文档没更新
