必须先确认 Symfony 6.4 项目骨架类型，纯 API 骨架需手动安装 twig-bundle 和 web-profiler-bundle；再安装 NelmioApiDocBundle v4.12+，配置 openapi 信息、路由及 APP_URL 环境变量，并为控制器添加 OA 注解或 PHP 8 Attributes，最后访问 /api/doc 即可运行交互式 OpenAPI 文档。
要在 Symfony 6.4 项目中搭建可运行、可生成、可交互的 OpenAPI 文档系统，必须先明确：Symfony 本身不内置 OpenAPI 支持，需借助第三方 Bundle 集成，且不同骨架（skeleton vs website-skeleton）的初始依赖差异会直接影响安装路径。
确认项目骨架类型并补全基础依赖
打开终端，进入你的 Symfony 6.4 项目根目录，执行：
composer show | grep -E "(symfony/skeleton|symfony/website-skeleton)"
若输出包含 symfony/skeleton，说明是纯 API 骨架——它默认不含 Twig、WebProfiler 或任何模板渲染能力，而 OpenAPI UI（如 Swagger UI）需要 HTML 渲染支持；此时必须手动安装 twig-bundle 和 web-profiler-bundle，否则后续文档页面无法加载。
执行：
composer require twig-bundle web-profiler-bundle
若已是 symfony/website-skeleton，则跳过此步。但注意：web-server-bundle 已弃用，不要装它，否则会与内置 PHP 内置服务器冲突。
安装 OpenAPI 集成 Bundle
推荐使用 NelmioApiDocBundle（当前兼容 Symfony 6.4 的稳定版本为 v4.12+）：
运行：
composer require nelmio/api-doc-bundle
该 Bundle 会自动执行 Flex recipe 注入配置。检查 config/bundles.php，确认存在：
Nelmio\ApiDocBundle\NelmioApiDocBundle::class => ['all' => true]
如果没自动注册，请手动添加这一行——【缺少这行会导致路由 /api/doc 不生效】。
配置 OpenAPI 文档入口与路由
第一步：在 config/packages/nelmio_api_doc.yaml 中写入基础配置：
openapi: '
info:
title: "My API"
version: "1.0.0"
servers:
- url: "%env(APP_URL)%"
第二步：确保路由已启用。打开 config/routes.yaml，添加：
nelmio_api_doc:
path: /api/doc
controller: nelmio_api_doc.controller.swagger_ui
第三步：设置环境变量 APP_URL。编辑 .env 文件，写入：
APP_URL=http://localhost:8000
这一步不能跳过——【若 APP_URL 为空或格式错误，Swagger UI 加载时会报“Invalid spec format”错误】。
为控制器添加 OpenAPI 注解
方法一：使用 PHPDoc 注解（最常用）
在 src/Controller/Api/UserController.php 的 action 方法上方添加：
/** * @OA\Get( * path="/api/users", * summary="获取用户列表", * @OA\Response(response="200", description="返回用户数组") * ) */
注意：需提前 use Nelmio\ApiDocBundle\Annotation as OA;
方法二：使用 Attributes（PHP 8+ 推荐）
替换为：
#[OA\Get( path: '/api/users', summary: '获取用户列表', responses: [new OA\Response(response: '200', description: '返回用户数组')] )]
这一步操作起来很简单，直接把注解写在 controller 方法上就行。但必须确保控制器类名和命名空间正确，否则注解不会被扫描到。
启动服务并访问文档
执行：
php -S localhost:8000 -t public
浏览器访问：
http://localhost:8000/api/doc
页面应显示交互式 Swagger UI，左侧列出所有带 OpenAPI 注解的端点。若页面空白或 404，请回查 routes.yaml 是否拼写错误、APP_URL 是否设值、以及 NelmioApiDocBundle 是否在 bundles.php 中启用。
