如何在Symfony的ApiPlatform中为控制器端点配置Swagger文档？

方法一：使用ApiPlatform原生操作属性 #

#[ApiResource]是为实体类设计的，无法直接作用于控制器。要让控制器中的端点被Swagger识别，需使用#[ApiOperation]配合#[ApiResponse]等属性标记方法：

use ApiPlatform\Metadata\ApiOperation;
use ApiPlatform\Metadata\ApiResponse;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\HttpFoundation\JsonResponse;

class CustomController
{
    #[Route('/my-endpoint', name: 'my_endpoint', methods: ['GET'])]
    #[ApiOperation(
        summary: '自定义GET端点',
        description: '这是一个在控制器中定义的独立端点，返回JSON格式的问候信息'
    )]
    #[ApiResponse(
        response: 200,
        description: '请求成功',
        content: new \ApiPlatform\Metadata\JsonContent(
            type: 'object',
            properties: [
                'message' => ['type' => 'string', 'example' => 'Hello, world!']
            ]
        )
    )]
    public function myEndpoint(): JsonResponse
    {
        return new JsonResponse(['message' => 'Hello, world!']);
    }
}

确保项目已安装api-platform/core，且ApiPlatform配置正确，它会自动扫描控制器中的这些属性并生成Swagger文档。

方法二：修复OpenAPI注释的识别问题 #

如果偏好使用@OA系列注释，需完成以下配置：

1. 安装依赖包：

composer require zircote/swagger-php

2. 修改config/packages/api_platform.yaml，确保扫描控制器路径并开启OpenAPI支持：

api_platform:
    openapi:
        version: 3.0.0
        title: '你的API名称'
        description: 'API功能描述'
    mapping:
        paths: ['%kernel.project_dir%/src/Controller', '%kernel.project_dir%/src/Entity']

3. 修正控制器注释，引入正确的命名空间：

use OpenApi\Annotations as OA;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\HttpFoundation\JsonResponse;

class CustomController
{
    /**
     * @Route("/my-endpoint", name="my_endpoint", methods={"GET"})
     * @OA\Get(
     *     path="/my-endpoint",
     *     summary="自定义GET端点",
     *     description="控制器中定义的独立端点示例",
     *     @OA\Response(
     *         response=200,
     *         description="请求成功",
     *         @OA\JsonContent(
     *             type="object",
     *             @OA\Property(
     *                 property="message",
     *                 type="string",
     *                 example="Hello, world!"
     *             )
     *         )
     *     )
     * )
     */
    public function myEndpoint(): JsonResponse
    {
        return new JsonResponse(['message' => 'Hello, world!']);
    }
}

PHP 8+环境下也可改用属性写法（#[OA\Get]等），效果一致。

核心注意点 #

• #[ApiResource]仅用于实体类，控制器方法必须用#[ApiOperation]标记。
• 使用注释方式时，必须确保依赖安装完整，且ApiPlatform配置包含控制器扫描路径。
• 避免混合使用实体关联控制器的方案（你之前尝试的方式），除非业务有特殊需求。

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