Skip to content

Add ErrorResource Schemes to OpenAPI documentation #6003

@f1amy

Description

@f1amy

Description
Currently, we have a way to document error HTTP status codes supported by an Operation with exceptionToStatus property, as well as adding our own documentation with openApi property.
That much is great, however by default we have limited information about errors in the OpenAPI documentation: an HTTP code, description and "string" as scheme.

With v3.2, we can now represent errors/exceptions as ErrorResource, which should give us the ability to show proper scheme of a response in documentation.

For that we need to have a way to map ErrorResources to specific Operations. Knowing what ErrorResources could be thrown, we can turn ErrorResource classes into OpenAPI documentation.

Example
A way to solve this would be by introducing to Operation class a new property errors, that contains a list of ErrorResources used:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;

#[ApiResource(
    operations: [
        new Get(
            uriTemplate: '/orders/{id}',
            errors: [
                OrderNotFoundError::class,
            ],
        ),
    ],
)]
class Order {}
use ApiPlatform\Metadata\ErrorResource;
use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;

#[ErrorResource(status: 404)]
class OrderNotFoundException extends \Exception implements ProblemExceptionInterface
{
    // ...
}

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions