-
-
Notifications
You must be signed in to change notification settings - Fork 924
Description
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
{
// ...
}