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)?

You might want to use subresource operation or describe response manually (as did I once). It's a common API platform problem. — Tarasovych
– Tarasovych, Commented Dec 27, 2019 at 10:50
I tried this as well, but I couldn't get it to work with my entity structure. LearningSkill is not a direct subresource of TeachingClass. I have the following entities: TeachingClass, TeachingClassLearningSkill, LearningSkill. — Nicodemuz
– Nicodemuz, Commented Dec 28, 2019 at 11:51

MetaClass · Accepted Answer · 2020-11-04 12:43:03Z

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

Collectives™ on Stack Overflow

Custom GET operation for API platform generates wrong documentation

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related