升级nelmio/api-doc-bundle后访问/api/doc.json无匹配路由怎么解决

问题原因 #

NelmioApiDocBundle 4.x版本重构了内部控制器命名，同时新增了文档区域（area）配置逻辑，3.x版本使用的nelmio_api_doc.controller.swagger控制器已被弃用，因此原有路由配置失效。

具体修改步骤 #

• 调整路由配置
  修改config/routes/nelmio_api_doc.yaml内容，替换控制器名，按需补充area参数：

app.swagger:
    path: /api/doc.json
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.openapi, area: 'default' }

如果你的项目配置了多文档区域，将area参数的值替换为你要访问的区域名即可。

如果想直接使用Bundle自带的默认路由配置，也可以直接替换整个nelmio_api_doc.yaml路由配置为以下内容，会自动注册JSON接口和UI页面：

nelmio_api_doc:
    resource: '@NelmioApiDocBundle/Resources/config/routing/swaggerui.xml'
    prefix: /api/doc

使用上述配置后，JSON文档的访问地址为/api/doc.json，UI页面访问地址为/api/doc。

• 清理Symfony缓存
  执行控制台命令清理缓存，让路由配置生效：
  php bin/console cache:clear

• 验证路由是否生效
  执行以下命令查看路由列表，确认/api/doc.json路由已正常注册：
  php bin/console debug:router | grep api/doc

内容的提问来源于stack exchange，提问作者Mayor of the Plattenbaus