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

Question

I have a symfony project, where I use api-platform.

I have an entity, and I have data providers for it. I am in trouble with definition of additional parameters for a collection endpoint.

An entity is called suggestion. It has to return collection of documents from elastic search.

An endpoint is:

/suggestion

This endpoint listens to additional GET parameters:

page, level

These two params are read each time, when the endpoint is requested.

In my SuggestionsCollectionDataProvider.php class I have:

/**
     * Retrieves a collection.
     *
     * @param string $resourceClass
     * @param string|null $operationName
     * @return \Generator
     */
    public function getCollection(string $resourceClass, string $operationName = null): \Generator
    {
        $query = $this->requestStack->getCurrentRequest()->query;
        // I am reading these two parameters from RequestStack
        
        // this one is built-in
        $page = max($query->get('page', 1), 1); 

        // this is a custom one
        $level = $query->get('level', 0); 
        ...

In my SuggestionRepository.php class:

/**
     * @return \Generator
     */
    public function find(int $page, int $level): \Generator
    {
        // here I can process with $level without problems

Page parameter is default parameter, that is generating in swagger for collections.

A screenshot from API platform generated Swagger doc:

But the page parameter is now the only parameter, that can be edited in web version.

I need to add more parameters (level in this case) to swagger and describe them, so the user/tester knows which parameter actually goes to this endpoint.

Main question:

How to tell api-platform, that I want a user/tester of the API (from client side) to enter some other parameters, i.e. level for example?

Solution 1

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:

Solution 2

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:

<?php

namespace 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.

Solution 3

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:

Solution 4

If someone end up here by expecting an additionnal GET parameter in the URL, for example if your routing {id} parameter is not parsed by the swagger test tool, you should just change this in @pedrouan solution:

"in" = "path",

View more solutions

Comments

[COil]

You should write where this content should be added.

[yivi]

@COil You mean the location of the configuration files? It's a bit outside the scope of the question, I think. That question would be something like "how can I can configure Api-Platform resources without using annotations?"

[Dom]

Change "swagger_context" to "openapi_context" if you are in the last versions

[Fabian Schmengler]

Attention, "required" = "true" works because the string "true" evaluates to true. "required" = "false" doesn't work, it must be "required" = false

[Fabian Schmengler]

And documentation is here: swagger.io/docs/specification/describing-parameters The Api Platform docs don't cover Swagger/OpenAPI specification much