Custom GET operation for API platform generates wrong documentation

Question

I have added the following operation under TeachingClass entity.

App\Entity\TeachingClass:
    collectionOperations:
        # ...
    itemOperations:
        # ...

        get_learning_skills:
            method: GET
            path: /auth/v1/teaching-class/{id}/learning-skills
            resourceClass: 'App\Entity\LearningSkill' # Doesn't seem to work
            controller: App\Controller\Api\LearningSkillApiController
            normalization_context:
                groups: ['learning_skill_list']
            security: 'is_granted("HAS_TEACHING_CLASS_ACCESS", object)'
            swagger_context:
                summary: "Retrieves the collection of LearningSkill resources belonging to a specific TeachingClass."
                description: "LearningSkills belonging to a specific TeachingClass"

The end-point correctly returns a collection of LearningSkill entities by the configured controller:

<?php

namespace App\Controller\Api;

use App\Entity\LearningSkill;
use App\Entity\TeachingClass;
use App\Repository\LearningSkillRepository;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\JsonResponse;

/**
 * Class LearningSkillApiController.
 */
class LearningSkillApiController
{
    private $learningSkillRepository;

    public function __construct(LearningSkillRepository $learningSkillRepository)
    {
        $this->learningSkillRepository = $learningSkillRepository;
    }

    public function __invoke(TeachingClass $data)
    {
        return $this->byTeachingClass($data);
    }

    private function byTeachingClass(TeachingClass $teachingClass)
    {
        return $this->learningSkillRepository->findByTeachingClass($teachingClass);
    }
}

However, my problem is that the generated API doc is wrong:

How do I make the documentation reflect that the response is a collection of LearningSkill entities (instead of a TeachingClass entity)?

Answer 1

I had the same problem with the report in the chapter9-api branch of my tutorial, which outputs instances of DayTotalsPerEmployee instead of the class the endpoint is on. My solution was to make a SwaggerDecorator. Below is one adapted for your operation.

It also sets the descriptions in components schemas referred to by the response 200 content. This is based on the assumption that your response is a collection response. It apip thinks it is an item response there may be some more work to to to make the swagger docs describe a collection response.

<?php

namespace App\Swagger;

use Symfony\Component\Serializer\Normalizer\NormalizerInterface;

final class SwaggerDecorator implements NormalizerInterface
{
    private $decorated;

    public function __construct(NormalizerInterface $decorated)
    {
        $this->decorated = $decorated;
    }

    public function normalize($object, string $format = null, array $context = [])
    {
        $summary = 'The collection of LearningSkill resources belonging to a specific TeachingClass.';
        $docs = $this->decorated->normalize($object, $format, $context);

        $docs['paths']['/auth/v1/teaching-class/{id}/learning-skills']['get']['responses']['200']['description'] = 'LearningSkills collection response';

        $responseContent = $docs['paths']['/auth/v1/teaching-class/{id}/learning-skills']['get']['responses']['200']['content'];
        $this->setByRef($docs, $responseContent['application/ld+json']['schema']['properties']['hydra:member']['items']['$ref'],
            'description', $summary);
        $this->setByRef($docs, $responseContent['application/json']['schema']['items']['$ref'],
            'description', $summary);

        return $docs;
    }

    public function supportsNormalization($data, string $format = null)
    {
        return $this->decorated->supportsNormalization($data, $format);
    }

    private function setByRef(&$docs, $ref, $key, $value)
    {
        $pieces = explode('/', substr($ref, 2));
        $sub =& $docs;
        foreach ($pieces as $piece) {
            $sub =& $sub[$piece];
        }
        $sub[$key] = $value;
    }
}

To configure the service add the following to api/config/services.yaml:

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