add a specific "documentation_formats" that may differ from the API "…

features/main/content_negotiation.feature

@@ -110,8 +110,8 @@ Feature: Content Negotiation support
     Then the response status code should be 406
     And the header "Content-Type" should be equal to "application/problem+json; charset=utf-8"
 
-  Scenario: If the request format is HTML, the error should be in HTML
-    When I add "Accept" header equal to "text/html"
+  Scenario: If the request format is XML, the error should be in XML
+    When I add "Accept" header equal to "application/xml"
     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"
+    And the header "Content-Type" should be equal to "application/xml; charset=utf-8"

src/Bridge/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php

@@ -88,7 +88,8 @@ public function load(array $configs, ContainerBuilder $container)
         $config = $this->processConfiguration($configuration, $configs);
         $formats = $this->getFormats($config['formats']);
         $errorFormats = $this->getFormats($config['error_formats']);
-        $this->handleConfig($container, $config, $formats, $errorFormats);
+        $documentationFormats = $this->getFormats($config['documentation_formats']);
+        $this->handleConfig($container, $config, $formats, $errorFormats, $documentationFormats);
 
         $loader = new XmlFileLoader($container, new FileLocator(__DIR__.'/../Resources/config'));
         $loader->load('api.xml');
@@ -153,8 +154,9 @@ public function load(array $configs, ContainerBuilder $container)
      * @param array            $config
      * @param array            $formats
      * @param array            $errorFormats
+     * @param array            $documentationFormats
      */
-    private function handleConfig(ContainerBuilder $container, array $config, array $formats, array $errorFormats)
+    private function handleConfig(ContainerBuilder $container, array $config, array $formats, array $errorFormats, array $documentationFormats)
     {
         $container->setParameter('api_platform.enable_entrypoint', $config['enable_entrypoint']);
         $container->setParameter('api_platform.enable_docs', $config['enable_docs']);
@@ -164,6 +166,7 @@ private function handleConfig(ContainerBuilder $container, array $config, array
         $container->setParameter('api_platform.exception_to_status', $config['exception_to_status']);
         $container->setParameter('api_platform.formats', $formats);
         $container->setParameter('api_platform.error_formats', $errorFormats);
+        $container->setParameter('api_platform.documentation_formats', $documentationFormats);
         $container->setParameter('api_platform.allow_plain_identifiers', $config['allow_plain_identifiers']);
         $container->setParameter('api_platform.eager_loading.enabled', $config['eager_loading']['enabled']);
         $container->setParameter('api_platform.eager_loading.max_joins', $config['eager_loading']['max_joins']);

src/Bridge/Symfony/Bundle/DependencyInjection/Configuration.php

@@ -222,6 +222,9 @@ public function getConfigTreeBuilder()
 
         $this->addFormatSection($rootNode, 'formats', [
             'jsonld' => ['mime_types' => ['application/ld+json']],
+        ]);
+        $this->addFormatSection($rootNode, 'documentation_formats', [
+            'jsonld' => ['mime_types' => ['application/ld+json']], // Hydra documentation, admin and PWA generator
             'json' => ['mime_types' => ['application/json']], // Swagger support
             'html' => ['mime_types' => ['text/html']], // Swagger UI support
         ]);

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

@@ -131,6 +131,7 @@
         <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>%api_platform.documentation_formats%</argument>
 
             <tag name="kernel.event_listener" event="kernel.request" method="onKernelRequest" priority="7" />
         </service>
@@ -205,7 +206,7 @@
             <argument>%api_platform.title%</argument>
             <argument>%api_platform.description%</argument>
             <argument>%api_platform.version%</argument>
-            <argument>%api_platform.formats%</argument>
+            <argument>%api_platform.documentation_formats%</argument>
         </service>
 
         <service id="api_platform.action.exception" class="ApiPlatform\Core\Action\ExceptionAction" public="true">

src/Bridge/Symfony/Bundle/Resources/config/routing/docs.xml

@@ -8,6 +8,7 @@
     <route id="api_doc" path="/docs.{_format}">
         <default key="_controller">api_platform.action.documentation</default>
         <default key="_api_respond">1</default>
+        <default key="_api_endpoint_type">documentation</default>
         <default key="_format" />
     </route>
 

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>%api_platform.documentation_formats%</argument>
             <argument>%api_platform.oauth.enabled%</argument>
             <argument>%api_platform.oauth.clientId%</argument>
             <argument>%api_platform.oauth.clientSecret%</argument>

src/EventListener/AddFormatListener.php

@@ -28,12 +28,14 @@ final class AddFormatListener
 {
     private $negotiator;
     private $formats;
+    private $documentationFormats;
     private $mimeTypes;
 
-    public function __construct(Negotiator $negotiator, array $formats)
+    public function __construct(Negotiator $negotiator, array $formats, array $documentationFormats = [])
     {
         $this->negotiator = $negotiator;
         $this->formats = $formats;
+        $this->documentationFormats = $documentationFormats;
     }
 
     /**
@@ -51,13 +53,15 @@ public function onKernelRequest(GetResponseEvent $event)
             return;
         }
 
-        $this->populateMimeTypes();
-        $this->addRequestFormats($request, $this->formats);
+        $requestAcceptedFormats = $this->getRequestAcceptedFormats($request);
+
+        $this->populateMimeTypes($requestAcceptedFormats);
+        $this->addRequestFormats($request, $requestAcceptedFormats);
 
         // Empty strings must be converted to null because the Symfony router doesn't support parameter typing before 3.2 (_format)
         if (null === $routeFormat = $request->attributes->get('_format') ?: null) {
             $mimeTypes = array_keys($this->mimeTypes);
-        } elseif (!isset($this->formats[$routeFormat])) {
+        } elseif (!isset($requestAcceptedFormats[$routeFormat])) {
             throw new NotFoundHttpException(sprintf('Format "%s" is not supported', $routeFormat));
         } else {
             $mimeTypes = Request::getMimeTypes($routeFormat);
@@ -84,11 +88,11 @@ public function onKernelRequest(GetResponseEvent $event)
                 return;
             }
 
-            throw $this->getNotAcceptableHttpException($mimeType);
+            throw $this->getNotAcceptableHttpException($mimeType ?? $requestFormat);
         }
 
         // Finally, if no Accept header nor Symfony request format is set, return the default format
-        foreach ($this->formats as $format => $mimeType) {
+        foreach ($requestAcceptedFormats as $format => $mimeType) {
             $request->setRequestFormat($format);
 
             return;
@@ -110,15 +114,17 @@ private function addRequestFormats(Request $request, array $formats)
 
     /**
      * Populates the $mimeTypes property.
+     *
+     * @param array $requestAcceptedFormats
      */
-    private function populateMimeTypes()
+    private function populateMimeTypes(array $requestAcceptedFormats)
     {
         if (null !== $this->mimeTypes) {
             return;
         }
 
         $this->mimeTypes = [];
-        foreach ($this->formats as $format => $mimeTypes) {
+        foreach ($requestAcceptedFormats as $format => $mimeTypes) {
             foreach ($mimeTypes as $mimeType) {
                 $this->mimeTypes[$mimeType] = $format;
             }
@@ -145,4 +151,16 @@ private function getNotAcceptableHttpException(string $accept, array $mimeTypes
             implode('", "', $mimeTypes)
         ));
     }
+
+    /**
+     * Retrieves the list of accepted format in the request depending on some parameters.
+     */
+    private function getRequestAcceptedFormats(Request $request): array
+    {
+        if (!$request->attributes->has('_api_endpoint_type')) {
+            return $this->formats;
+        }
+
+        return 'documentation' === $request->attributes->get('_api_endpoint_type') ? $this->documentationFormats : $this->formats;
+    }
 }

tests/Bridge/Symfony/Bundle/DependencyInjection/ApiPlatformExtensionTest.php

@@ -450,6 +450,7 @@ private function getPartialContainerBuilderProphecy($test = false)
             'api_platform.collection.pagination.partial_parameter_name' => 'partial',
             'api_platform.description' => 'description',
             'api_platform.error_formats' => ['jsonproblem' => ['application/problem+json'], 'jsonld' => ['application/ld+json']],
+            'api_platform.documentation_formats' => ['jsonld' => ['application/ld+json'], 'json' => ['application/json'], 'html' => ['text/html']],
             'api_platform.formats' => ['jsonld' => ['application/ld+json'], 'jsonhal' => ['application/hal+json']],
             'api_platform.exception_to_status' => [ExceptionInterface::class => Response::HTTP_BAD_REQUEST, InvalidArgumentException::class => Response::HTTP_BAD_REQUEST],
             'api_platform.title' => 'title',

tests/Bridge/Symfony/Bundle/DependencyInjection/ConfigurationTest.php

@@ -57,6 +57,9 @@ public function testDefaultConfig()
             'version' => '1.0.0',
             'formats' => [
                 'jsonld' => ['mime_types' => ['application/ld+json']],
+            ],
+            'documentation_formats' => [
+                'jsonld' => ['mime_types' => ['application/ld+json']],
                 'json' => ['mime_types' => ['application/json']],
                 'html' => ['mime_types' => ['text/html']],
             ],

tests/EventListener/AddFormatListenerTest.php

@@ -32,7 +32,7 @@ public function testNoResourceClass()
         $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
         $event = $eventProphecy->reveal();
 
-        $listener = new AddFormatListener(new Negotiator(), ['notexist' => 'application/vnd.notexist']);
+        $listener = new AddFormatListener(new Negotiator(), ['notexist' => 'application/vnd.notexist'], []);
         $listener->onKernelRequest($event);
 
         $this->assertNull($request->getFormat('application/vnd.notexist'));
@@ -47,7 +47,7 @@ public function testSupportedRequestFormat()
         $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
         $event = $eventProphecy->reveal();
 
-        $listener = new AddFormatListener(new Negotiator(), ['xml' => ['text/xml']]);
+        $listener = new AddFormatListener(new Negotiator(), ['xml' => ['text/xml']], []);
         $listener->onKernelRequest($event);
 
         $this->assertSame('xml', $request->getRequestFormat());
@@ -63,7 +63,7 @@ public function testRespondFlag()
         $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
         $event = $eventProphecy->reveal();
 
-        $listener = new AddFormatListener(new Negotiator(), ['xml' => ['text/xml']]);
+        $listener = new AddFormatListener(new Negotiator(), ['xml' => ['text/xml']], []);
         $listener->onKernelRequest($event);
 
         $this->assertSame('xml', $request->getRequestFormat());
@@ -83,7 +83,7 @@ public function testUnsupportedRequestFormat()
         $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
         $event = $eventProphecy->reveal();
 
-        $listener = new AddFormatListener(new Negotiator(), ['json' => ['application/json']]);
+        $listener = new AddFormatListener(new Negotiator(), ['json' => ['application/json']], []);
         $listener->onKernelRequest($event);
 
         $this->assertSame('json', $request->getRequestFormat());
@@ -98,7 +98,7 @@ public function testSupportedAcceptHeader()
         $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
         $event = $eventProphecy->reveal();
 
-        $listener = new AddFormatListener(new Negotiator(), ['binary' => ['application/octet-stream'], 'json' => ['application/json']]);
+        $listener = new AddFormatListener(new Negotiator(), ['binary' => ['application/octet-stream'], 'json' => ['application/json']], []);
         $listener->onKernelRequest($event);
 
         $this->assertSame('json', $request->getRequestFormat());
@@ -113,7 +113,7 @@ public function testAcceptAllHeader()
         $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
         $event = $eventProphecy->reveal();
 
-        $listener = new AddFormatListener(new Negotiator(), ['binary' => ['application/octet-stream'], 'json' => ['application/json']]);
+        $listener = new AddFormatListener(new Negotiator(), ['binary' => ['application/octet-stream'], 'json' => ['application/json']], []);
         $listener->onKernelRequest($event);
 
         $this->assertSame('binary', $request->getRequestFormat());
@@ -133,7 +133,7 @@ public function testUnsupportedAcceptHeader()
         $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
         $event = $eventProphecy->reveal();
 
-        $listener = new AddFormatListener(new Negotiator(), ['binary' => ['application/octet-stream'], 'json' => ['application/json']]);
+        $listener = new AddFormatListener(new Negotiator(), ['binary' => ['application/octet-stream'], 'json' => ['application/json']], []);
         $listener->onKernelRequest($event);
     }
 
@@ -150,7 +150,7 @@ public function testInvalidAcceptHeader()
         $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
         $event = $eventProphecy->reveal();
 
-        $listener = new AddFormatListener(new Negotiator(), ['json' => ['application/json']]);
+        $listener = new AddFormatListener(new Negotiator(), ['json' => ['application/json']], []);
         $listener->onKernelRequest($event);
     }
 
@@ -164,7 +164,7 @@ public function testAcceptHeaderTakePrecedenceOverRequestFormat()
         $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
         $event = $eventProphecy->reveal();
 
-        $listener = new AddFormatListener(new Negotiator(), ['xml' => ['application/xml'], 'json' => ['application/json']]);
+        $listener = new AddFormatListener(new Negotiator(), ['xml' => ['application/xml'], 'json' => ['application/json']], []);
         $listener->onKernelRequest($event);
 
         $this->assertSame('json', $request->getRequestFormat());
@@ -182,7 +182,42 @@ public function testInvalidRouteFormat()
         $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
         $event = $eventProphecy->reveal();
 
-        $listener = new AddFormatListener(new Negotiator(), ['json' => ['application/json']]);
+        $listener = new AddFormatListener(new Negotiator(), ['json' => ['application/json']], []);
         $listener->onKernelRequest($event);
     }
+
+    public function testSupportedDocumentationAcceptHeader()
+    {
+        $request = new Request([], [], ['_api_respond' => '1', '_api_endpoint_type' => 'documentation']);
+        $request->setRequestFormat('json');
+
+        $eventProphecy = $this->prophesize(GetResponseEvent::class);
+        $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
+        $event = $eventProphecy->reveal();
+
+        $listener = new AddFormatListener(new Negotiator(), ['xml' => ['text/xml']], ['json' => ['application/json']]);
+        $listener->onKernelRequest($event);
+
+        $this->assertSame('json', $request->getRequestFormat());
+        $this->assertSame('application/json', $request->getMimeType($request->getRequestFormat()));
+    }
+
+    /**
+     * @expectedException \Symfony\Component\HttpKernel\Exception\NotAcceptableHttpException
+     * @expectedExceptionMessageRegExp /^Requested format "(jsonld|application\/ld\+json)" is not supported. Supported MIME types are "application\/json".$/
+     */
+    public function testUnsupportedDocumentationRequestFormat()
+    {
+        $request = new Request([], [], ['_api_respond' => '1', '_api_endpoint_type' => 'documentation']);
+        $request->setRequestFormat('jsonld');
+
+        $eventProphecy = $this->prophesize(GetResponseEvent::class);
+        $eventProphecy->getRequest()->willReturn($request)->shouldBeCalled();
+        $event = $eventProphecy->reveal();
+
+        $listener = new AddFormatListener(new Negotiator(), ['xml' => ['text/xml']], ['json' => ['application/json']]);
+        $listener->onKernelRequest($event);
+
+        $this->assertSame('json', $request->getRequestFormat());
+    }
 }

tests/Fixtures/app/config/config_test.yml

@@ -37,10 +37,18 @@ api_platform:
         xml:                           ['application/xml', 'text/xml']
         json:                          ['application/json']
         html:                          ['text/html']
+    documentation_formats:
+        jsonld:                        ['application/ld+json']
+        jsonhal:                       ['application/hal+json']
+        jsonapi:                       ['application/vnd.api+json']
+        xml:                           ['application/xml', 'text/xml']
+        json:                          ['application/json']
+        html:                          ['text/html']
     error_formats:
         jsonproblem:                   ['application/problem+json']
         jsonld:                        ['application/ld+json']
         jsonapi:                       ['application/vnd.api+json']
+        xml:                           ['application/xml', 'text/xml']
     graphql:                           true
     name_converter:                    'app.name_converter'
     enable_fos_user:                   true