Symfony项目中NelmioApiDocBundle注解不生效问题求助

以下是几个直接有效的修复方向：

1. 切换为属性形式的OpenApi注解 #

你当前混合使用了Symfony属性路由和PHPDoc格式的OpenApi注解，部分版本的NelmioApiDocBundle对属性注解的兼容性更好。修改控制器代码如下：

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Annotation\Route;
use OpenApi\Attributes as OA;

class HealthcheckController extends AbstractController
{
    #[Route('/healthcheck', name: 'healthcheck', methods: 'GET')]
    #[OA\Get(
        summary: "检查应用健康状态",
        description: "该接口用于验证应用是否正常运行",
        responses: [
            new OA\Response(
                response: 200,
                description: "应用健康时返回OK",
                content: new OA\JsonContent(
                    properties: [
                        new OA\Property(property: "result", type: "string", example: "OK")
                    ]
                )
            )
        ],
        security: []
    )]
    public function index(): JsonResponse
    {
        return new JsonResponse(["result" => "OK"], 200);
    }
}

2. 验证配置文件结构完整性 #

确保nelmio_api_doc.yaml最外层包含nelmio_api_doc:节点，完整配置如下：

nelmio_api_doc:
    documentation:
        info:
            title: My App
            description: This is an awesome app!
            version: 1.0.0
    areas: # 过滤要生成文档的路由区域
        path_patterns:
            - ^/api(?!/doc$) # 包含/api下除/api/doc外的路由
            - ^/healthcheck # 包含/healthcheck路由

3. 清理缓存 #

Symfony的路由或文档缓存可能导致新接口未被识别，执行命令清理dev环境缓存：

php bin/console cache:clear --env=dev

4. 确认路由已正确注册 #

执行命令检查healthcheck路由是否存在：

php bin/console debug:router

如果路由未列出，需确认config/services.yaml中已启用App\Controller\命名空间的自动配置。

内容的提问来源于stack exchange，提问作者Skyshufeu