docs: add guide to migrate from FOSRestBundle

Author: Deuchnord

core/migration-guides/fosrestbundle.md

@@ -0,0 +1,17 @@
+# Migrate from FOSRestBundle
+
+[FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle) is a popular bundle to rapidly develop RESTful APIs with Symfony.
+
+In September 2021, [it has been announced to be deprecated](https://twitter.com/lsmith/status/1440216817876627459) and its maintainers recommended to use API Platform instead. This page provides a guide to help developers migrating from FOSRestBundle to API Platform.
+
+## Features comparison
+
+The table below provides a list of the main features you can find in FOSRestBundle 3.1, and their equivalents in API Platform 2.6.
+
+| Feature | FOSRestBundle | API Platform
+| --- | --- | ---
+| **Make CRUD endpoints** | Create a controller extending the `AbstractFOSRestController` abstract class, make your magic manually in your methods and return responses through the `handleView()` provided by FOSRest's `ControllerTrait`. (see [The view layer](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/2-the-view-layer.rst)) | Add the `ApiResource` attribute to your entities, and enable operations you desire inside. By default, every operations are activated. (see [Operations](https://api-platform.com/docs/core/operations/))
+| **Make custom controllers** | Same as above | Create an invokable class, do your magic inside, and declare it in your entity's `ApiResource`. (see [Creating Custom Operations and Controllers](https://api-platform.com/docs/core/controllers/))
+| **Routing system** (with native documentation support) | Annotate your controllers with FOSRest's route annotations that are the most suitable to your needs. (see [Full default annotations](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/annotations-reference.rst)) | This is handled by the `ApiResource` attribute mentionned above.
+| **Hook into the requests handling** | Listen to FOSRest's events to modify the requests before they come into your controllers, and the responses after they come out of them. (see [Listener support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/3-listener-support.rst)) | Listen to API Platform's events to modify the HTTP responses. (see [The event System](https://api-platform.com/docs/core/events/))
+| **Handle errors** | Map the exeptions to HTTP statuses in the `fos_rest.exception` parameter. (see [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst)) | Map the exeptions to HTTP statuses in the `api_platform.exception_to_status` parameter. (see [Errors Handling](https://api-platform.com/docs/core/errors/))