NelmioApiDocBundle需手动配置路由、path_patterns、securitySchemes和模型注解才能正常工作：默认仅扫描/api路由，需添加/v1等前缀；必须配置securitySchemes和security才显示Authorize按钮；DTO需用#[Model]、#[OA\Property]等注解显式声明。
直接能用，但默认配置只扫 /api 路由，且不带认证、区域划分或模型描述——这些得手动补。
安装和基础路由必须配对才出页面
只运行 composer require nelmio/api-doc-bundle 不够，还得确保路由文件存在并启用 UI 控制器。Flex 通常会自动生成 config/routes/nelmio_api_doc.yaml，但如果没生成，你得手动建：
app.swagger_ui:
path: /api/doc
methods: GET
defaults: { _controller: nelmio_api_doc.controller.swagger_ui }访问 /api/doc 时如果报错 “Controller not found”，大概率是这个路由没生效，或者缓存没清（bin/console cache:clear）。
path_patterns 配置决定哪些接口被收录
默认只收录 ^/api(?!/doc$) 的路由，意思是：以 /api 开头、但排除 /api/doc 自身。如果你的 API 在 /v1/users 或 /graphql 下，它不会出现。
- 要包含
/v1，改成- ^/v1 - 要同时支持多个前缀，写成列表：
- ^/api和- ^/v1 - 如果用了子域名（如
api.example.com），还得加host_patterns，否则跨域路由不识别
改完配置后必须清缓存，否则新规则不加载。
安全方案（Bearer、API Key）得手动定义 components
#[IsGranted] 能自动标记权限，但不会生成 OpenAPI 的 securitySchemes 或 security 字段——这部分必须在 config/packages/nelmio_api_doc.yaml 里硬写：
nelmio_api_doc:
documentation:
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- BearerAuth: []漏掉 components.securitySchemes，Swagger UI 就不会显示 “Authorize” 按钮；漏掉顶层 security，所有接口都默认为“未认证”。两者缺一不可。
模型字段不显示？检查是否用了 Symfony 属性或 JMS 注解
NelmioApiDocBundle 默认不扫描实体属性生成请求/响应结构，除非你显式告诉它：
- 用
#[MapRequestPayload]标记控制器参数，它才会解析 DTO 类的属性 - DTO 类里字段没注解（如
#[OA\Property]或 JMS@JMS\Expose），字段就直接消失 - 返回类型写
Response或JsonResponse，文档里只会显示 “string”，不是实际结构——得用#[Response]+#[OA\JsonContent]手动描述
最常被忽略的是：DTO 类本身没加 #[Model]，导致同名类在不同命名空间下冲突，或者干脆不被识别为模型。
区域（Areas）、缓存、多版本文档这些进阶能力都建立在路径匹配和模型可识别的基础上——先把 path_patterns 和属性标注跑通，再拆分区域或加认证，不然越配越乱。
