如何在Symfony的nelmio-api-doc bundle中隐藏指定接口的/rpc前缀？

针对你需要在Swagger文档中为部分JSON-RPC接口隐藏全局配置的/rpc前缀的需求，以下是几种可行方案：

1. 单个接口用注解手动覆盖路径 #

如果只是少数接口需要隐藏前缀，最直接的方式是在控制器方法上用Nelmio的OpenAPI注解手动指定不带前缀的路径，覆盖全局配置：

OpenAPI 3.x 用法（推荐） #

use Nelmio\ApiDocBundle\Annotation\Operation;
use OpenApi\Attributes as OA;

#[Operation(
    path: '/json-rpc/endpoint', // 直接写不带/rpc的路径
    summary: 'JSON-RPC接口示例'
)]
#[Route('/rpc/json-rpc/endpoint', methods: ['POST'])] // 实际路由仍保留/rpc前缀
public function jsonRpcEndpoint(): JsonResponse
{
    // 业务逻辑
}

旧版注解（Nelmio < 4.x） #

use Nelmio\ApiDocBundle\Annotation\ApiDoc;

/**
 * @ApiDoc(
 *     path="/json-rpc/endpoint",
 *     description="JSON-RPC接口示例"
 * )
 * @Route("/rpc/json-rpc/endpoint", methods={"POST"})
 */
public function jsonRpcEndpoint(): JsonResponse
{
    // 业务逻辑
}

2. 自定义处理器批量处理指定接口 #

如果有大量接口需要隐藏前缀，可以通过Nelmio的自定义处理器动态修改Swagger文档中的路径：

步骤1：创建自定义注解标记需要处理的接口 #

// src/Annotation/HideRpcPrefix.php
namespace App\Annotation;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD)]
class HideRpcPrefix
{
}

步骤2：实现Nelmio处理器 #

// src/Processor/HideRpcPrefixProcessor.php
namespace App\Processor;

use App\Annotation\HideRpcPrefix;
use Nelmio\ApiDocBundle\Processor\ProcessorInterface;
use OpenApi\Annotations\OpenApi;
use ReflectionClass;

class HideRpcPrefixProcessor implements ProcessorInterface
{
    public function process(OpenApi $api): void
    {
        foreach ($api->paths as $path => $pathItem) {
            foreach ($pathItem->operations as $operation) {
                // 通过反射获取方法上的自定义注解
                $reflection = new ReflectionClass($operation->_context['class']);
                $method = $reflection->getMethod($operation->_context['method']);
                if ($method->getAttributes(HideRpcPrefix::class)) {
                    // 替换路径开头的/rpc前缀
                    $newPath = preg_replace('/^\/rpc/', '', $path);
                    // 更新路径并删除旧路径
                    $api->paths->addPath($newPath, $pathItem);
                    unset($api->paths->paths[$path]);
                    break;
                }
            }
        }
    }
}

步骤3：注册处理器（Symfony 服务配置） #

# config/services.yaml
services:
    App\Processor\HideRpcPrefixProcessor:
        tags: ['nelmio_api_doc.processor']

之后在需要隐藏前缀的控制器方法上添加#[HideRpcPrefix]注解，处理器会自动在Swagger文档中去掉/rpc前缀。

3. 拆分文档组配置不同前缀 #

如果可以按接口类型分组，可在nelmio_api_doc.yaml中配置多个文档组，分别设置前缀：

# config/packages/nelmio_api_doc.yaml
nelmio_api_doc:
    documentation:
        - name: RPC
          prefix: /rpc
          # RPC接口组的其他配置
        - name: PublicJSONRPC
          prefix: '' # 该组接口不带前缀
          # 公共JSON-RPC接口组的其他配置

然后在需要隐藏前缀的控制器方法上指定归属的文档组：

#[ApiDoc(documentation: 'PublicJSONRPC')]
#[Route('/json-rpc/endpoint', methods: ['POST'])]
public function publicJsonRpcEndpoint(): JsonResponse
{
    // 业务逻辑
}

这样该接口会出现在PublicJSONRPC文档组中，Swagger显示的路径不带/rpc前缀。

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