API Platform 的 Swagger 文档需显式启用 enable_swagger 和 enable_swagger_ui，且实体类必须标注 #[ApiResource] 才会出现在 /api/docs；开发时访问 http://localhost:8000/api/docs，生产环境默认禁用 UI 以保障安全。
API Platform 默认启用 Swagger 文档生成，不需要额外安装包或写路由——只要项目已正确初始化，/api/docs 就能直接访问交互式 UI。关键在配置文件是否启用、实体类是否带元数据、以及开发环境是否暴露了文档端点。
确认 api_platform.yaml 中 swagger 开关已打开
API Platform 的 Swagger 功能不是“默认全开”，而是依赖 enable_swagger_ui 显式控制。很多开发者改了 title 却打不开页面，就是卡在这一步。
-
enable_swagger: true控制 OpenAPI JSON 规范是否生成（必须为true） -
enable_swagger_ui: true控制前端 UI 是否可用（开发时建议设为true） - 若使用 Mercure 或 Hydra，
include_type: true会影响 JSON-LD 字段，但不影响 Swagger 渲染
示例最小可用配置：
api_platform: enable_swagger: true enable_swagger_ui: true title: "My API" version: "1.0.0"
实体类必须带 #[ApiResource] 才会出现在文档中
Swagger 文档内容完全由 PHP 层的元数据驱动，不是扫描控制器或路由。没加 #[ApiResource] 的类，哪怕有对应 Controller，也不会出现在 /api/docs 里。
- 仅声明
#[ApiResource]就会自动生成标准 CRUD 端点（GET /collection、GET /item、POST、PUT、DELETE） - 想隐藏某个操作？用
operations显式列出需要的，比如new Get()+new Post()，不写Delete就不会显示 DELETE 行 - 字段级描述靠 PHPDoc +
@OA\Property注解（需装zircote/swagger-php），但基础字段名、类型、必填性由 Doctrine 类型和#[Assert\*]自动推导
访问路径不是 /swagger 或 /docs，而是 /api/docs
这是最容易输错的点。API Platform 不走通用路径约定，硬编码为 /api/docs（除非你主动重配 docs_formats）。
- 开发时直接访问
http://localhost:8000/api/docs（Symfony CLI 默认端口） - 若用 Nginx/Apache，确保 rewrite 规则放行
/api/docs路径，不要被try_files重定向到 index.php 以外的 fallback - 生产环境默认禁用 UI：
enable_swagger_ui: '%env(bool:ENABLE_SWAGGER_UI)%'是更安全的做法，避免文档外泄
常见 404 或空白页的三个实际原因
不是代码写错了，而是环境或权限链断了。
- 运行的是
prod环境但没跑php bin/console cache:warmup --env=prod，导致注解未解析，文档为空 - 实体类用了
final关键字，API Platform 无法代理生成元数据（报错类似Cannot instantiate interface ApiPlatform\Metadata\Resource\Factory\ResourceMetadataFactoryInterface） - PHP OPcache 启用但未刷新，改了注解却看不到更新——执行
php bin/console cache:clear后还得killall php-fpm && systemctl restart php-fpm（取决于部署方式）
真正麻烦的从来不是配置项本身，而是这些隐式依赖：注解解析器是否就绪、缓存是否干净、环境变量是否透传、HTTP 服务器是否放行静态资源路径。每一步都得单独验证，不能只盯着 YAML 文件改来改去。
