Question

我在TeachingClass实体下添加了以下操作。

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"

端点通过配置的控制器正确返回LearningSkill实体的集合：

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

但是，我的问题是生成的API文档错误：

我如何使文档反映出响应是LearningSkill实体（而不是TeachingClass实体）的集合？

Answer 1

我的tutorial的Chapter9-api分支中的报告存在相同的问题，该分支输出DayTotalsPerEmployee的实例而不是终结点所在的类。我的解决方案是制作SwaggerDecorator。以下是适合您的操作的一种。

它还在响应200内容所引用的组件模式中设置描述。这是基于您的响应是集合响应的假设。 apip认为这是一项项目回应，可能需要做更多的工作才能使庞大的文档描述集合回应。

<?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;
    }
}

要配置服务，请将以下内容添加到api / config / services.yaml：

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

API平台的自定义GET操作生成错误的文档

1 个答案: