Как добавить свою ошибку на документацию "/ api" api-platform

Question

Я разрабатываю приложение с Symfony 4 и API-платформой, очень классный пакет.

Я создал пользовательскую ошибку xxxException, основываясь на https://api -platform.com / docs / core / errors / . Я использовал его на почтовой операции, и он отлично работает.

Теперь я хочу раскрыть свою ошибку в документации API при доступе к some-url/api.

как это сделать, как показано на рисунке.

Answer 1

Опираясь на ответ Симеона, я хотел бы добавить, что его пример переопределяет все ключи для его примера '/ login', потому что он переопределяет полный массив для этой пост-операции.

Если вы хотите переопределить или добавить документацию только для определенного кода статуса http, то вы можете сделать это следующим образом

public function normalize($object, $format = null, array $context = [])
    {
        $docs = $this->decorated->normalize($object, $format, $context);

        // Document custom errors that we get from exceptions registered in config/packages/api_platform.yaml
        $docs['paths']['/api/books']['post']['responses']['409'] = ['description' => 'The book is no longer available'];

        return $docs;
    }

Вы можете добавить конфигурацию кодов статуса http, сопоставив свой пользовательскийисключения из кода в config / packages / api_platform.yaml

api_platform:
    mapping:
        paths: ['%kernel.project_dir%/src/Entity']
    exception_to_status:
        # The 4 following handlers are registered by default, keep those lines to prevent unexpected side effects
        Symfony\Component\Serializer\Exception\ExceptionInterface: 400 # Use a raw status code (recommended)
        ApiPlatform\Core\Exception\InvalidArgumentException: 'HTTP_BAD_REQUEST' # Or a `Symfony\Component\HttpFoundation\Response`'s constant
        ApiPlatform\Core\Exception\FilterValidationException: 400
        Doctrine\ORM\OptimisticLockException: 409

        # Custom mapping
        App\Exception\SpaceUnavailableException: 409

Answer 2

Вы можете создать SwaggerDecorator как объяснено здесь .

Затем в вашем классе App\Swagger\SwaggerDecorator в вашем методе normalize вы можете изменить документацию следующим образом (вот пример добавления документации и ответов на пользовательскую операцию входа в систему):

public function normalize($object, $format = null, array $context = [])
{
    $documentation = $this->decorated->normalize($object, $format, $context);

    $documentation['paths']['/login'] = [ // "/login" is the path of the operation
        'post' => [ // "post" is the http request method
            'responses' => [
                '200' => [ // 200 is the http response code
                    'description' => 'Successful log in.',
                ],
                '401' => [ // 401 another http response code
                    'description' => 'Bad credentials.',
                ],
            ],
        ],
    ];

    return $documentation;
}

Примечание: переменная документации - это просто массив или объект, реализующий ArrayAccess, вы можете сбросить его и отредактировать по своему усмотрению.