Symfony中如何为API Platform端点添加Swagger自定义GET参数？

Got it, let's fix that missing level parameter in your Swagger docs for the /suggestion endpoint. Here are a couple of straightforward ways to handle this in API Platform:

Method 1: Use API Platform's Built-in QueryParameterFilter (Quickest Fix) #

This is the simplest approach if you just need to expose the parameter without extra customization like descriptions or validation rules.

1. First, make sure you have the API Platform core package installed (it's usually included by default, but if not run composer require api-platform/core).
2. Add the ApiFilter annotation to your Suggestion entity, targeting the level parameter:

// src/Entity/Suggestion.php
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Doctrine\Orm\Filter\QueryParameterFilter;
use ApiPlatform\Metadata\ApiResource;

#[ApiResource]
// Add this line to expose the level query parameter
#[ApiFilter(QueryParameterFilter::class, properties: ['level' => null])]
class Suggestion
{
    // Your existing entity properties, getters/setters, and annotations here
}

The ['level' => null] config tells API Platform to expose the parameter but skip automatic ORM filtering (since you're already handling it in your repository). This will immediately add level to the Swagger docs for the /suggestion collection endpoint.

Method 2: Custom OpenAPI Extension (For Full Control) #

If you want to add descriptions, set parameter types, mark it as required, or tweak other Swagger-specific details, use a custom OpenAPI extension:

1. Create the extension class:

// src/OpenApi/SuggestionOpenApiExtension.php
namespace App\OpenApi;

use ApiPlatform\OpenApi\Factory\OpenApiFactoryInterface;
use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\Parameter;
use ApiPlatform\OpenApi\Model\PathItem;
use ApiPlatform\OpenApi\OpenApi;

class SuggestionOpenApiExtension implements OpenApiFactoryInterface
{
    public function __construct(private readonly OpenApiFactoryInterface $decorated) {}

    public function __invoke(array $context = []): OpenApi
    {
        $openApi = ($this->decorated)($context);
        
        // Target the /suggestion collection endpoint's GET operation
        $pathItem = $openApi->getPaths()->getPath('/suggestion');
        if (!$pathItem instanceof PathItem) {
            return $openApi;
        }

        $getOperation = $pathItem->getGet();
        if (!$getOperation instanceof Operation) {
            return $openApi;
        }

        // Add your custom level parameter with details
        $parameters = $getOperation->getParameters();
        $parameters[] = new Parameter(
            name: 'level',
            in: 'query',
            description: 'Filter suggestions by their difficulty level (e.g., "beginner", "intermediate", "advanced")',
            required: false, // Set to true if the parameter is mandatory
            schema: ['type' => 'string'] // Adjust to 'integer' if level is a numeric value
        );

        // Update the operation and path with the new parameter
        $getOperation = $getOperation->withParameters($parameters);
        $pathItem = $pathItem->withGet($getOperation);
        $openApi->getPaths()->addPath('/suggestion', $pathItem);

        return $openApi;
    }
}

2. Register the service (Symfony 5+ auto-registers services, but if you're on an older version, add this to config/services.yaml):

services:
    App\OpenApi\SuggestionOpenApiExtension:
        decorates: 'api_platform.open_api.factory'
        arguments: ['@.inner']

After clearing your cache (php bin/console cache:clear), your Swagger docs will show the level parameter with all your custom settings.

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