How to ask for additional GET parameters in an endpoint of api-platform using swagger docs?

Finally figured it out.

I haven't found a documentation for it yet, but I found a way.

In an entity class Suggestion.php I've added some lines of annotations:

namespace App\Entity;use ApiPlatform\Core\Annotation\ApiProperty;use ApiPlatform\Core\Annotation\ApiResource;use Symfony\Component\Serializer\Annotation\Groups;use Symfony\Component\Validator\Constraints as Assert;/** * Class Suggestion. Represents an entity for an item from the suggestion result set. * @package App\Entity * @ApiResource( *     collectionOperations={ *          "get"={ *              "method"="GET", *              "swagger_context" = { *                  "parameters" = { *                      { *                          "name" = "level", *                          "in" = "query", *                          "description" = "Levels available in result", *                          "required" = "true", *                          "type" : "array", *                          "items" : { *                              "type" : "integer" *                          } *                      } *                  } *               } *          } *     }, *     itemOperations={"get"} * ) */

The result view in API platform swagger DOCs:

Adding "swagger_context" to the get annotation didn't work for me in Api Platform core version 2.4.6. Instead, I used the instructions provided at API Platform - Overriding the OpenAPI Specification

In my case, I had to deviate from the instructions a little bit. In the overridden normalize method, I had to remove the existing parameter first, then added the customized definition to the $doc parameters array. As pedrouan did, I was able to add the required=true property and it worked in the same manner.

In services.yaml I added:

    App\Swagger\SwaggerEventRequireDecorator:         decorates: 'api_platform.swagger.normalizer.api_gateway'         arguments: [ '@App\Swagger\SwaggerEventRequireDecorator.inner' ]         autoconfigure: false

In App\Swagger folder, I added the following class:

<?phpnamespace App\Swagger;use Symfony\Component\Serializer\Normalizer\NormalizerInterface;final class SwaggerEventRequireDecorator implements NormalizerInterface{    private $decorated;    public function __construct(NormalizerInterface $decorated)    {        $this->decorated = $decorated;    }    public function normalize($object, $format = null, array $context = [])    {        $docs = $this->decorated->normalize($object, $format, $context);        $customDefinition = [            'name' => 'event',            'description' => 'ID of the event the activities belong to.',            'in' => 'query',            'required' => 'true',            'type' => 'integer'        ];//         e.g. remove an existing event parameter        $docs['paths']['/scheduleamap-api/activities']['get']['parameters'] = array_values(array_filter($docs['paths']['/scheduleamap-api/activities']['get']['parameters'], function ($param) {            return $param['name'] !== 'event';        }));    // e.g. add the new definition for event    $docs['paths']['/scheduleamap-api/activities']['get']['parameters'][] = $customDefinition;        // Remove other restricted parameters that will generate errors.        $docs['paths']['/scheduleamap-api/activities']['get']['parameters'] = array_values(array_filter($docs['paths']['/scheduleamap-api/activities']['get']['parameters'], function ($param) {            return $param['name'] !== 'event[]';        }));        return $docs;    }    public function supportsNormalization($data, $format = null)    {        return $this->decorated->supportsNormalization($data, $format);    }}

Note:

1. I also have autowire and autoconfig set to true in services.yaml.

2. I added a custom Data Provider to require the event property filter be set in all api requests to the activity entity resource. The above customization does not require it to be set when doing direct fetch or url get requests.

If someone needs to do something similar, but using XML configuration:

<collectionOperation name="find_duplicated_items">    <attribute name="method">GET</attribute>    <attribute name="path">/items/find_duplicates</attribute>    <attribute name="controller">App\Infrastructure\Http\Items\FindDuplicates</attribute>     <attribute name="openapi_context">        <attribute name="parameters">            <attribute>                <attribute name="name">someProperty</attribute>                <attribute name="in">query</attribute>                <attribute name="required">true</attribute>                <attribute name="description">List foos and bars</attribute>                <attribute name="schema">                     <attribute name="type">array</attribute>                     <attribute name="items">                        <attribute name="type">integer</attribute>                     </attribute>                </attribute>            </attribute>                    <attribute>                <attribute name="name">ageDays</attribute>                <attribute name="in">query</attribute>                <attribute name="required">false</attribute>                <attribute name="description">Max age in days</attribute>                <attribute name="default">5</attribute>                <attribute name="schema">                    <attribute name="type">integer</attribute>                </attribute>            </attribute>        </attribute>    </attribute></collectionOperation>

Which gets you this: