Fosrestbundle: Add upgrade instructions for deprecated routing loader

[Tobion]

We need better upgrade instructions for switching from the automatic route generation loader to SF Core routing loader.

One part:
Using the method shortcuts also works when using the symfony core annotation loader as they extend the core Route annotation. So we can keep them in rest-bundle and don't need to deprecate them. The only thing that changes is that it changes the route name as rest-bundle used a different naming convention and it removes the .{_format} suffix from routes if you used routing_loader.include_format option (which was enabled by default).

Before:

Acme\Controller\TestController:
    type: rest
    resource: Acme\Controller\TestController

After:

Acme\Controller\TestController:
    type: annotation
    resource: Acme\Controller\TestController

Migrate to explicit routes with the help of bin/console debug:router --show-controllers

[alexander-schranz]

We should also document that for controllers generating routes using the ClassResourceInterface is gone that they need to update adding the annotations or installing the FOSRestRoutingBundle.

[enumag]

It should also be noted that @NamePrefix has no effect after changing type from rest to annotation.

[Tobion]

@xabbuh disabling the routing loader with enabled: false still triggers the deprecation by error

Enabling the route generation feature is deprecated since FOSRestBundle 2.8.

routing_loader:
        enabled: false

[Tobion]

What I've also noticed while trying to upgrade our project to rest-bundle 2.8@dev:

If you use the JMS serializer instead of the symfony one and resolve the deprecations like setting serialize_exceptions: false, you lose the ability to render errors in anything but html. This is because \Symfony\Component\ErrorHandler\ErrorRenderer\SerializerErrorRenderer requires the symfony serializer and if that is not installed, you will just get the \Symfony\Component\ErrorHandler\ErrorRenderer\HtmlErrorRenderer.

So one of the rest-bundle objectives has been to work with both jms and symfony serializer. But for error rendering this is not the case currently. So I think the rest-bundle needs an error render for jms based on SerializerErrorRenderer or it provides an error renderer for the \FOS\RestBundle\Serializer\Serializer interface that should abstract away the differences.

[xabbuh]

@Tobion I guess the deprecation should be fixed with #2181. Can you confirm?

In #2161 I added the JmsSerializerErrorRenderer to be able to simulate such a behaviour in tests. To me a similar class could be shipped by the JmsSerializerBundle. We could also include one in FOSRestBundle though I think it would better be located there. Maybe @goetas also has some opinion on this topic.

[Tobion]

Yeah in theory is could be shipped with the JmsSerializerBundle. But the wiring would need to depend on the fos_rest.service.serializer configuration I guess. So in the end it's probably easier to just put it in the rest-bundle for now.

[xabbuh]

2182 will integrate a SerializerErrorRenderer leveraging our own Serializer interface.

[goetas]

I did not follow much the conversation, but if is possible to help, will be happy to do so.
Are you planning some new major release?