add: [DOC] Custom Subresources Data Provider examples (#1454)

* add: Custom Subresources Data Provider examples

I added exemple to help user to custom the subreshttps://github.com/api-platform/core/issues/2321#issuecomment-437357871

It would be nice to set a trace in the official doc.

* changes for the review

* add the listing top SubresourceDataProviderInterface

* Update core/data-providers.md

* Update core/data-providers.md

* Update core/data-providers.md

* Update core/data-providers.md

* Update core/data-providers.md

* Update core/data-providers.md

Co-authored-by: Vincent <[email protected]>

Author: Snowbaha

core/data-providers.md

@@ -17,6 +17,8 @@ For a given resource, you can implement two kinds of interface:
   is used when fetching a collection.
 * the [`ItemDataProviderInterface`](https://github.com/api-platform/core/blob/2.6/src/DataProvider/ItemDataProviderInterface.php)
   is used when fetching items.
+* the [`SubresourceDataProviderInterface`](https://github.com/api-platform/core/blob/2.6/src/DataProvider/SubresourceDataProviderInterface.php)
+  is used when fetching items.
 
 Both implementations can also implement a third, optional, interface called
 ['RestrictedDataProviderInterface'](https://github.com/api-platform/core/blob/2.6/src/DataProvider/RestrictedDataProviderInterface.php)
@@ -126,6 +128,49 @@ services:
 
 You can find a full working example in the [API Platform's demo application](https://github.com/api-platform/demo/blob/main/api/src/DataProvider/TopBookItemDataProvider.php).
 
+## Custom Subresources Data Provider
+
+You can add custom logic or update subresources data provider with the SubresourceDataProviderInterface .
+
+```php
+<?php
+// api/src/DataProvider/BlogPostCollectionDataProvider.php
+
+namespace App\DataProvider;
+
+use ApiPlatform\Core\DataProvider\SubresourceDataProviderInterface;
+use ApiPlatform\Core\DataProvider\RestrictedDataProviderInterface;
+use App\Entity\BlogPost;
+
+final class BlogPostSubresourceDataProvider implements SubresourceDataProviderInterface, RestrictedDataProviderInterface
+{
+    public function supports(string $resourceClass, string $operationName = null, array $context = []): bool
+    {
+        return BlogPost::class === $resourceClass;
+    }
+
+    public function getSubresource(string $resourceClass, array $identifiers, array $context, string $operationName = null): iterable
+    {
+        // Retrieve the blog post collection from somewhere
+        $blogPosts = $this->subresourceDataProvider->getSubresource($resourceClass, $identifiers, $context, $operationName);
+        // write your own logic
+
+        return blogPosts;
+    }
+}
+```
+
+Declare the service in your services configuration:
+
+```yaml
+# api/config/services.yaml
+services:
+    # ...
+    'App\DataProvider\BlogPostSubresourceDataProvider':
+        arguments:
+            - '@api_platform.doctrine.orm.default.subresource_data_provider'
+```
+
 ## Injecting the Serializer in an `ItemDataProvider`
 
 In some cases, you may need to inject the `Serializer` in your `DataProvider`. There are no issues with the