[RFC] Support for DTOs / resource representation classes

[teohhanhui]

We should support resource representation classes as an intermediary so that our resource classes can be clean / strongly typed.

To illustrate: https://gist.github.com/teohhanhui/970cf7d5bff27530aa3935a1566f67bf

[teohhanhui]

nb. @dunglas even if the type check is performed in the normalizer, it's still not a good error message when we'd expect to get validation errors instead. I think it's a symptom of a design problem when validation is not done using the Symfony Validator.

[teohhanhui]

Uhh, more importantly, input validation is more than just checking for the correct types and required values. Having a resource representation class is a really powerful thing as it allows supporting all kinds of validation and authorization scenarios.

[er1z]

What are benefits in real apps?

[bertrandseurot]

+1
@er1z Especially useful for specific roles actions. Avoid a lot of complexity and tricks

Actually when you add contextual serializer groups (according to the user role), the swagger documentation is incomplete (properties key missing). You can actually create your own DTO, but you have to manually hydrate your entity in an event subscriber, and the route appears disconnected of your resources routes in the swagger UI interface (not Front developpers friendly)

@ApiResource(relatedResource="Book") ?

[teohhanhui]

@Bertranddev I imagine it should be the other way around. @ApiResource should be on the actual resource class itself, which declares its representation classes.

[er1z]

Sounds legit. You're right that creating DTOs, currently, is not very convenient but the best way to make the app looking the same regardless the data is fetched via entity or generated in some way.

One request — keep docs actual, especially if someone do not use any annotations because right now it requires too much of guessing. Switching to YAML/XML needs to dig into sources. :(

[dunglas]

Fixed (at least partially) by #2235