NelmioApiDocBundle v4中/api/revoke路由未显示于API文档的问题

NelmioApiDocBundle v4 默认仅扫描关联了控制器方法的路由来生成API文档。你在security.yaml中定义的/api/revoke路由没有绑定任何控制器方法，因此不会被Bundle自动识别并收录到文档中。

方法1：手动在配置文件中添加路由文档 #

修改config/packages/nelmio_api_doc.yaml，在documentation的paths节点下手动定义该路由的API文档信息：

nelmio_api_doc:
    documentation:
        info:
            title: 你的API名称
            version: 1.0.0
        paths:
            /api/revoke:
                post:
                    summary: 吊销Bearer令牌
                    security:
                        - BearerAuth: []
                    responses:
                        '200':
                            description: 令牌吊销成功
                        '401':
                            description: 未授权或令牌无效
    areas:
        path_patterns:
            - ^/api

方法2：创建空控制器绑定路由 #

新建一个极简控制器，绑定/api/revoke路由并添加ApiDoc注解，无需编写业务逻辑（因为security.yaml已处理请求）：

<?php

namespace App\Controller;

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

class TokenController extends AbstractController
{
    #[Route('/api/revoke', name: 'api_revoke', methods: ['POST'])]
    #[OA\Post(summary: '吊销Bearer令牌')]
    #[OA\Response(response: 200, description: '令牌吊销成功')]
    #[OA\Response(response: 401, description: '未授权或令牌无效')]
    #[OA\Security(name: 'BearerAuth')]
    public function revoke(): Response
    {
        return new Response(null, Response::HTTP_OK);
    }
}

之后可删除security.yaml中重复的路由定义，或确保路由名称一致。

方法3：通过事件监听动态添加文档 #

创建事件监听器，在API文档构建前手动注入/api/revoke的OpenAPI信息：

<?php

namespace App\EventListener;

use Nelmio\ApiDocBundle\Event\PreBuildEvent;
use OpenApi\Annotations as OA;

class AddRevokeRouteDocListener
{
    public function __invoke(PreBuildEvent $event): void
    {
        $openapi = $event->getOpenApi();
        
        $postOperation = new OA\Post(
            summary: '吊销Bearer令牌',
            responses: [
                new OA\Response(response: 200, description: '令牌吊销成功'),
                new OA\Response(response: 401, description: '未授权或令牌无效'),
            ],
            security: [['BearerAuth' => []]]
        );
        
        $pathItem = new OA\PathItem();
        $pathItem->post = $postOperation;
        $openapi->paths['/api/revoke'] = $pathItem;
    }
}

在config/services.yaml中注册监听器：

services:
    App\EventListener\AddRevokeRouteDocListener:
        tags:
            - { name: kernel.event_listener, event: nelmio_api_doc.pre_build }

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