如何在“/api”文档 api-platform 上添加我的自定义错误

Question

我正在使用 symfony 4 和 api-platform 开发一个应用程序，这是一个非常棒的软件包。

我根据 https://api-platform.com/docs/core/errors/ 创建了一个自定义错误 xxxException。我在 post 操作中使用它并且工作正常。

现在我想在访问 some-url/api.

时在 api 文档中公开我的错误

how to do it like the following image.

Answer 1

您可以按照 here 的说明创建一个 SwaggerDecorator。

然后在 App\Swagger\SwaggerDecorator class 的 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的对象，您可以转储它并根据需要进行编辑。

Answer 2

基于 Simeons 的回答，我想补充一点，他的示例覆盖了他的“/login”示例的所有键，因为他覆盖了 post 操作的完整数组。

如果您只想覆盖或添加特定 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;
    }

您可以通过将自定义异常映射到 config/packages/api_platform.yaml

中的代码来添加配置您的 http 状态代码

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

如何在“/api”文档 api-platform 上添加我的自定义错误

How to add my custom error on "/api" documentation api-platform

error-handling

symfony

api-platform.com