[RFR] Allow to specify formats per resources/operations

features/main/content_negotiation.feature

@@ -115,3 +115,36 @@ Feature: Content Negotiation support
     And I send a "GET" request to "/dummies/666"
     Then the response status code should be 404
     And the header "Content-Type" should be equal to "text/html; charset=utf-8"
+
+  Scenario: Retrieve a collection in JSON should not be possible if the format has been removed at resource level
+    When I add "Accept" header equal to "application/json"
+    And I send a "GET" request to "/dummy_custom_formats"
+    Then the response status code should be 406
+    And the header "Content-Type" should be equal to "application/problem+json; charset=utf-8"
+
+  Scenario: Post an CSV body allowed on a single resource
+    When I add "Accept" header equal to "application/xml"
+    And I add "Content-Type" header equal to "text/csv"
+    And I send a "POST" request to "/dummy_custom_formats" with body:
+    """
+    name
+    Kevin
+    """
+    Then the response status code should be 201
+    And the header "Content-Type" should be equal to "application/xml; charset=utf-8"
+    And the response should be equal to
+    """
+    <?xml version="1.0"?>
+    <response><id>1</id><name>Kevin</name></response>
+    """
+
+  Scenario: Retrieve a collection in CSV should be possible if the format is at resource level
+    When I add "Accept" header equal to "text/csv"
+    And I send a "GET" request to "/dummy_custom_formats"
+    Then the response status code should be 200
+    And the header "Content-Type" should be equal to "text/csv; charset=utf-8"
+    And the response should be equal to
+    """
+    id,name
+    1,Kevin
+    """

src/Annotation/ApiResource.php

@@ -32,6 +32,7 @@
  *     @Attribute("description", type="string"),
  *     @Attribute("fetchPartial", type="bool"),
  *     @Attribute("forceEager", type="bool"),
+ *     @Attribute("formats", type="array"),
  *     @Attribute("filters", type="string[]"),
  *     @Attribute("graphql", type="array"),
  *     @Attribute("hydraContext", type="array"),
@@ -135,6 +136,13 @@ final class ApiResource
      */
     private $forceEager;
 
+    /**
+     * @see https://github.com/Haehnchen/idea-php-annotation-plugin/issues/112
+     *
+     * @var array
+     */
+    private $formats;
+
     /**
      * @see https://github.com/Haehnchen/idea-php-annotation-plugin/issues/112
      *

src/Api/FormatsProvider.php

@@ -0,0 +1,85 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Core\Api;
+
+use ApiPlatform\Core\Exception\InvalidArgumentException;
+use ApiPlatform\Core\Metadata\Resource\Factory\ResourceMetadataFactoryInterface;
+
+/**
+ * {@inheritdoc}
+ *
+ * @author Anthony GRASSIOT <antograssiot@free.fr>
+ */
+final class FormatsProvider implements FormatsProviderInterface
+{
+    private $configuredFormats;
+    private $resourceMetadataFactory;
+
+    public function __construct(ResourceMetadataFactoryInterface $resourceMetadataFactory, array $configuredFormats)
+    {
+        $this->resourceMetadataFactory = $resourceMetadataFactory;
+        $this->configuredFormats = $configuredFormats;
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @throws InvalidArgumentException
+     */
+    public function getFormatsFromAttributes(array $attributes): array
+    {
+        if (!$attributes || !isset($attributes['resource_class'])) {
+            return $this->configuredFormats;
+        }
+
+        $resourceMetadata = $this->resourceMetadataFactory->create($attributes['resource_class']);
+
+        if (!$formats = $resourceMetadata->getOperationAttribute($attributes, 'formats', [], true)) {
+            return $this->configuredFormats;
+        }
+
+        if (!\is_array($formats)) {
+            throw new InvalidArgumentException(sprintf("The 'formats' attributes must be an array, %s given for resource class '%s'.", \gettype($formats), $attributes['resource_class']));
+        }
+
+        return $this->getOperationFormats($formats);
+    }
+
+    /**
+     * Filter and populate the acceptable formats.
+     *
+     * @throws InvalidArgumentException
+     */
+    private function getOperationFormats(array $annotationFormats): array
+    {
+        $resourceFormats = [];
+        foreach ($annotationFormats as $format => $value) {
+            if (!is_numeric($format)) {
+                $resourceFormats[$format] = (array) $value;
+                continue;
+            }
+            if (!\is_string($value)) {
+                throw new InvalidArgumentException(sprintf("The 'formats' attributes value must be a string when trying to include an already configured format, %s given.", \gettype($value)));
+            }
+            if (array_key_exists($value, $this->configuredFormats)) {
+                $resourceFormats[$value] = $this->configuredFormats[$value];
+                continue;
+            }
+
+            throw new InvalidArgumentException(sprintf("You either need to add the format '%s' to your project configuration or declare a mime type for it in your annotation.", $value));
+        }
+
+        return $resourceFormats;
+    }
+}

src/Api/FormatsProviderInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Core\Api;
+
+/**
+ * Extracts formats for a given operation according to the retrieved Metadata.
+ *
+ * @author Anthony GRASSIOT <antograssiot@free.fr>
+ */
+interface FormatsProviderInterface
+{
+    /**
+     * Finds formats for an operation.
+     */
+    public function getFormatsFromAttributes(array $attributes): array;
+}

src/Bridge/Symfony/Bundle/Action/SwaggerUiAction.php

@@ -13,10 +13,13 @@
 
 namespace ApiPlatform\Core\Bridge\Symfony\Bundle\Action;
 
+use ApiPlatform\Core\Api\FormatsProviderInterface;
 use ApiPlatform\Core\Documentation\Documentation;
+use ApiPlatform\Core\Exception\InvalidArgumentException;
 use ApiPlatform\Core\Exception\RuntimeException;
 use ApiPlatform\Core\Metadata\Resource\Factory\ResourceMetadataFactoryInterface;
 use ApiPlatform\Core\Metadata\Resource\Factory\ResourceNameCollectionFactoryInterface;
+use ApiPlatform\Core\Util\RequestAttributesExtractor;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
@@ -37,7 +40,7 @@ final class SwaggerUiAction
     private $title;
     private $description;
     private $version;
-    private $formats;
+    private $formats = [];
     private $oauthEnabled;
     private $oauthClientId;
     private $oauthClientSecret;
@@ -46,8 +49,12 @@ final class SwaggerUiAction
     private $oauthTokenUrl;
     private $oauthAuthorizationUrl;
     private $oauthScopes;
+    private $formatsProvider;
 
-    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, ResourceMetadataFactoryInterface $resourceMetadataFactory, NormalizerInterface $normalizer, \Twig_Environment $twig, UrlGeneratorInterface $urlGenerator, string $title = '', string $description = '', string $version = '', array $formats = [], $oauthEnabled = false, $oauthClientId = '', $oauthClientSecret = '', $oauthType = '', $oauthFlow = '', $oauthTokenUrl = '', $oauthAuthorizationUrl = '', $oauthScopes = [])
+    /**
+     * @throws InvalidArgumentException
+     */
+    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, ResourceMetadataFactoryInterface $resourceMetadataFactory, NormalizerInterface $normalizer, \Twig_Environment $twig, UrlGeneratorInterface $urlGenerator, string $title = '', string $description = '', string $version = '', /* FormatsProviderInterface */ $formatsProvider = [], $oauthEnabled = false, $oauthClientId = '', $oauthClientSecret = '', $oauthType = '', $oauthFlow = '', $oauthTokenUrl = '', $oauthAuthorizationUrl = '', $oauthScopes = [])
     {
         $this->resourceNameCollectionFactory = $resourceNameCollectionFactory;
         $this->resourceMetadataFactory = $resourceMetadataFactory;
@@ -57,7 +64,6 @@ public function __construct(ResourceNameCollectionFactoryInterface $resourceName
         $this->title = $title;
         $this->description = $description;
         $this->version = $version;
-        $this->formats = $formats;
         $this->oauthEnabled = $oauthEnabled;
         $this->oauthClientId = $oauthClientId;
         $this->oauthClientSecret = $oauthClientSecret;
@@ -66,10 +72,30 @@ public function __construct(ResourceNameCollectionFactoryInterface $resourceName
         $this->oauthTokenUrl = $oauthTokenUrl;
         $this->oauthAuthorizationUrl = $oauthAuthorizationUrl;
         $this->oauthScopes = $oauthScopes;
+
+        if (\is_array($formatsProvider)) {
+            if ($formatsProvider) {
+                // Only trigger notification for non-default argument
+                @trigger_error('Using an array as formats provider is deprecated since API Platform 2.3 and will not be possible anymore in API Platform 3', E_USER_DEPRECATED);
+            }
+            $this->formats = $formatsProvider;
+
+            return;
+        }
+        if (!$formatsProvider instanceof FormatsProviderInterface) {
+            throw new InvalidArgumentException(sprintf('The "$formatsProvider" argument is expected to be an implementation of the "%s" interface.', FormatsProviderInterface::class));
+        }
+
+        $this->formatsProvider = $formatsProvider;
     }
 
     public function __invoke(Request $request)
     {
+        // BC check to be removed in 3.0
+        if (null !== $this->formatsProvider) {
+            $this->formats = $this->formatsProvider->getFormatsFromAttributes(RequestAttributesExtractor::extractAttributes($request));
+        }
+
         $documentation = new Documentation($this->resourceNameCollectionFactory->create(), $this->title, $this->description, $this->version, $this->formats);
 
         return new Response($this->twig->render('@ApiPlatform/SwaggerUi/index.html.twig', $this->getContext($request, $documentation)));

src/Bridge/Symfony/Bundle/Resources/config/api.xml

@@ -63,6 +63,11 @@
         </service>
         <service id="ApiPlatform\Core\Api\IriConverterInterface" alias="api_platform.iri_converter" />
 
+        <service id="api_platform.formats_provider" class="ApiPlatform\Core\Api\FormatsProvider">
+            <argument type="service" id="api_platform.metadata.resource.metadata_factory"></argument>
+            <argument>%api_platform.formats%</argument>
+        </service>
+
         <!-- Serializer -->
 
         <service id="api_platform.serializer.context_builder" class="ApiPlatform\Core\Serializer\SerializerContextBuilder" public="false">
@@ -130,7 +135,7 @@
         <!-- kernel.request priority must be < 8 to be executed after the Firewall -->
         <service id="api_platform.listener.request.add_format" class="ApiPlatform\Core\EventListener\AddFormatListener">
             <argument type="service" id="api_platform.negotiator" />
-            <argument>%api_platform.formats%</argument>
+            <argument type="service" id="api_platform.formats_provider"></argument>
 
             <tag name="kernel.event_listener" event="kernel.request" method="onKernelRequest" priority="7" />
         </service>
@@ -154,7 +159,7 @@
         <service id="api_platform.listener.request.deserialize" class="ApiPlatform\Core\EventListener\DeserializeListener">
             <argument type="service" id="api_platform.serializer" />
             <argument type="service" id="api_platform.serializer.context_builder" />
-            <argument>%api_platform.formats%</argument>
+            <argument type="service" id="api_platform.formats_provider" />
 
             <tag name="kernel.event_listener" event="kernel.request" method="onKernelRequest" priority="2" />
         </service>
@@ -205,7 +210,7 @@
             <argument>%api_platform.title%</argument>
             <argument>%api_platform.description%</argument>
             <argument>%api_platform.version%</argument>
-            <argument>%api_platform.formats%</argument>
+            <argument type="service" id="api_platform.formats_provider" />
         </service>
 
         <service id="api_platform.action.exception" class="ApiPlatform\Core\Action\ExceptionAction" public="true">

src/Bridge/Symfony/Bundle/Resources/config/swagger.xml

@@ -58,7 +58,7 @@
             <argument>%api_platform.title%</argument>
             <argument>%api_platform.description%</argument>
             <argument>%api_platform.version%</argument>
-            <argument>%api_platform.formats%</argument>
+            <argument type="service" id="api_platform.formats_provider" />
             <argument>%api_platform.oauth.enabled%</argument>
             <argument>%api_platform.oauth.clientId%</argument>
             <argument>%api_platform.oauth.clientSecret%</argument>

src/Documentation/Action/DocumentationAction.php

@@ -13,8 +13,11 @@
 
 namespace ApiPlatform\Core\Documentation\Action;
 
+use ApiPlatform\Core\Api\FormatsProviderInterface;
 use ApiPlatform\Core\Documentation\Documentation;
+use ApiPlatform\Core\Exception\InvalidArgumentException;
 use ApiPlatform\Core\Metadata\Resource\Factory\ResourceNameCollectionFactoryInterface;
+use ApiPlatform\Core\Util\RequestAttributesExtractor;
 use Symfony\Component\HttpFoundation\Request;
 
 /**
@@ -28,15 +31,32 @@ final class DocumentationAction
     private $title;
     private $description;
     private $version;
-    private $formats;
+    private $formats = [];
+    private $formatsProvider;
 
-    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, string $title = '', string $description = '', string $version = '', array $formats = [])
+    /**
+     * @throws InvalidArgumentException
+     */
+    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, string $title = '', string $description = '', string $version = '', /* FormatsProviderInterface */ $formatsProvider = [])
     {
         $this->resourceNameCollectionFactory = $resourceNameCollectionFactory;
         $this->title = $title;
         $this->description = $description;
         $this->version = $version;
-        $this->formats = $formats;
+        if (\is_array($formatsProvider)) {
+            if ($formatsProvider) {
+                // Only trigger notification for non-default argument
+                @trigger_error('Using an array as formats provider is deprecated since API Platform 2.3 and will not be possible anymore in API Platform 3', E_USER_DEPRECATED);
+            }
+            $this->formats = $formatsProvider;
+
+            return;
+        }
+        if (!$formatsProvider instanceof FormatsProviderInterface) {
+            throw new InvalidArgumentException(sprintf('The "$formatsProvider" argument is expected to be an implementation of the "%s" interface.', FormatsProviderInterface::class));
+        }
+
+        $this->formatsProvider = $formatsProvider;
     }
 
     public function __invoke(Request $request = null): Documentation
@@ -47,6 +67,12 @@ public function __invoke(Request $request = null): Documentation
                 $context['api_gateway'] = true;
             }
             $request->attributes->set('_api_normalization_context', $request->attributes->get('_api_normalization_context', []) + $context);
+
+            $attributes = RequestAttributesExtractor::extractAttributes($request);
+        }
+        // BC check to be removed in 3.0
+        if (null !== $this->formatsProvider) {
+            $this->formats = $this->formatsProvider->getFormatsFromAttributes($attributes ?? []);
         }
 
         return new Documentation($this->resourceNameCollectionFactory->create(), $this->title, $this->description, $this->version, $this->formats);