compatibility with OpenAPI 3.0

features/openapi/docs.feature

@@ -393,3 +393,44 @@ Feature: Documentation support
       "$ref": "#\/components\/schemas\/WrappedResponseEntity-read"
     }
     """
+
+  Scenario: Retrieve the OpenAPI documentation with 3.0 specification
+    Given I send a "GET" request to "/docs.jsonopenapi?spec_version=3.0.0"
+    Then the response status code should be 200
+    And the response should be in JSON
+    And the JSON node "openapi" should be equal to "3.0.0"
+    And the JSON node "components.schemas.DummyBoolean" should be equal to:
+    """
+    {
+      "type": "object",
+      "description": "",
+      "deprecated": false,
+      "properties": {
+        "id": {
+          "readOnly": true,
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "isDummyBoolean": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "dummyBoolean": {
+          "readOnly": true,
+          "type": "boolean"
+        }
+      }
+    }
+    """

src/Documentation/Action/DocumentationAction.php

@@ -21,6 +21,7 @@
 use ApiPlatform\OpenApi\Factory\OpenApiFactoryInterface;
 use ApiPlatform\OpenApi\OpenApi;
 use ApiPlatform\OpenApi\Serializer\ApiGatewayNormalizer;
+use ApiPlatform\OpenApi\Serializer\LegacyOpenApiNormalizer;
 use ApiPlatform\OpenApi\Serializer\OpenApiNormalizer;
 use ApiPlatform\State\ProcessorInterface;
 use ApiPlatform\State\ProviderInterface;
@@ -60,7 +61,11 @@ public function __invoke(Request $request = null)
             return new Documentation($this->resourceNameCollectionFactory->create(), $this->title, $this->description, $this->version);
         }
 
-        $context = ['api_gateway' => $request->query->getBoolean(ApiGatewayNormalizer::API_GATEWAY), 'base_url' => $request->getBaseUrl()];
+        $context = [
+            'api_gateway' => $request->query->getBoolean(ApiGatewayNormalizer::API_GATEWAY),
+            'base_url' => $request->getBaseUrl(),
+            'spec_version' => (string) $request->query->get(LegacyOpenApiNormalizer::SPEC_VERSION),
+        ];
         $request->attributes->set('_api_normalization_context', $request->attributes->get('_api_normalization_context', []) + $context);
         $format = $this->getRequestFormat($request, $this->documentationFormats);
 
@@ -78,7 +83,18 @@ private function getOpenApiDocumentation(array $context, string $format, Request
     {
         if ($this->provider && $this->processor) {
             $context['request'] = $request;
-            $operation = new Get(class: OpenApi::class, read: true, serialize: true, provider: fn () => $this->openApiFactory->__invoke($context), normalizationContext: [ApiGatewayNormalizer::API_GATEWAY => $context['api_gateway'] ?? null], outputFormats: $this->documentationFormats);
+            $operation = new Get(
+                class: OpenApi::class,
+                read: true,
+                serialize: true,
+                provider: fn () => $this->openApiFactory->__invoke($context),
+                normalizationContext: [
+                    ApiGatewayNormalizer::API_GATEWAY => $context['api_gateway'] ?? null,
+                    LegacyOpenApiNormalizer::SPEC_VERSION => $context['spec_version'] ?? null,
+                ],
+                outputFormats: $this->documentationFormats
+            );
+
             if ('html' === $format) {
                 $operation = $operation->withProcessor('api_platform.swagger_ui.processor')->withWrite(true);
             }

src/Documentation/Action/EntrypointAction.php

@@ -17,6 +17,7 @@
 use ApiPlatform\Metadata\Get;
 use ApiPlatform\Metadata\Resource\Factory\ResourceNameCollectionFactoryInterface;
 use ApiPlatform\Metadata\Resource\ResourceNameCollection;
+use ApiPlatform\OpenApi\Serializer\LegacyOpenApiNormalizer;
 use ApiPlatform\State\ProcessorInterface;
 use ApiPlatform\State\ProviderInterface;
 use Symfony\Component\HttpFoundation\Request;
@@ -41,7 +42,10 @@ public function __construct(
     public function __invoke(Request $request)
     {
         static::$resourceNameCollection = $this->resourceNameCollectionFactory->create();
-        $context = ['request' => $request];
+        $context = [
+            'request' => $request,
+            'spec_version' => (string) $request->query->get(LegacyOpenApiNormalizer::SPEC_VERSION),
+        ];
         $request->attributes->set('_api_platform_disable_listeners', true);
         $operation = new Get(outputFormats: $this->documentationFormats, read: true, serialize: true, class: Entrypoint::class, provider: [self::class, 'provide']);
         $request->attributes->set('_api_operation', $operation);

src/OpenApi/Command/OpenApiCommand.php

@@ -53,7 +53,9 @@ protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $filesystem = new Filesystem();
         $io = new SymfonyStyle($input, $output);
-        $data = $this->normalizer->normalize($this->openApiFactory->__invoke(), 'json');
+        $data = $this->normalizer->normalize($this->openApiFactory->__invoke(), 'json', [
+            'spec_version' => $input->getOption('spec-version'),
+        ]);
         $content = $input->getOption('yaml')
             ? Yaml::dump($data, 10, 2, Yaml::DUMP_OBJECT_AS_MAP | Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE | Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK)
             : (json_encode($data, \JSON_PRETTY_PRINT | \JSON_UNESCAPED_SLASHES) ?: '');

src/OpenApi/Serializer/LegacyOpenApiNormalizer.php

@@ -0,0 +1,67 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * 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\OpenApi\Serializer;
+
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+
+final class LegacyOpenApiNormalizer implements NormalizerInterface
+{
+    public const SPEC_VERSION = 'spec_version';
+    private array $defaultContext = [
+        self::SPEC_VERSION => '3.1.0',
+    ];
+
+    public function __construct(private readonly NormalizerInterface $decorated, $defaultContext = [])
+    {
+        $this->defaultContext = array_merge($this->defaultContext, $defaultContext);
+    }
+
+    public function normalize(mixed $object, string $format = null, array $context = []): array
+    {
+        $openapi = $this->decorated->normalize($object, $format, $context);
+
+        if ('3.0.0' !== ($context['spec_version'] ?? null)) {
+            return $openapi;
+        }
+
+        $schemas = &$openapi['components']['schemas'];
+        $openapi['openapi'] = '3.0.0';
+        foreach ($openapi['components']['schemas'] as $name => $component) {
+            foreach ($component['properties'] ?? [] as $property => $value) {
+                if (\is_array($value['type'] ?? false)) {
+                    foreach ($value['type'] as $type) {
+                        $schemas[$name]['properties'][$property]['anyOf'][] = ['type' => $type];
+                    }
+                    unset($schemas[$name]['properties'][$property]['type']);
+                }
+                unset($schemas[$name]['properties'][$property]['owl:maxCardinality']);
+            }
+        }
+
+        return $openapi;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supportsNormalization(mixed $data, string $format = null, array $context = []): bool
+    {
+        return $this->decorated->supportsNormalization($data, $format, $context);
+    }
+
+    public function getSupportedTypes($format): array
+    {
+        return $this->decorated->getSupportedTypes($format);
+    }
+}

src/Symfony/Bundle/Resources/config/openapi.xml

@@ -58,7 +58,12 @@
 
         <service id="api_platform.openapi.normalizer.api_gateway"  class="ApiPlatform\OpenApi\Serializer\ApiGatewayNormalizer" public="false" decorates="api_platform.openapi.normalizer" decoration-priority="-1">
             <argument type="service" id="api_platform.openapi.normalizer.api_gateway.inner" />
-            <tag name="serializer.normalizer" priority="-780" />
+            <tag name="serializer.normalizer" />
+        </service>
+
+        <service id="api_platform.openapi.normalizer.legacy"  class="ApiPlatform\OpenApi\Serializer\LegacyOpenApiNormalizer" public="false" decorates="api_platform.openapi.normalizer.api_gateway" decoration-priority="-2">
+            <argument type="service" id="api_platform.openapi.normalizer.legacy.inner" />
+            <tag name="serializer.normalizer" />
         </service>
         <service id="ApiPlatform\OpenApi\Factory\OpenApiFactoryInterface" alias="api_platform.openapi.factory" />
 

tests/Documentation/Action/DocumentationActionTest.php

@@ -52,9 +52,10 @@ public function testDocumentationAction(): void
         $requestProphecy->headers = $this->prophesize(ParameterBagInterface::class)->reveal();
         $requestProphecy->getBaseUrl()->willReturn('/api')->shouldBeCalledTimes(1);
         $queryProphecy->getBoolean('api_gateway')->willReturn(true)->shouldBeCalledTimes(1);
+        $queryProphecy->get('spec_version')->willReturn('3.1.0')->shouldBeCalledTimes(1);
         $attributesProphecy->get('_api_normalization_context', [])->willReturn(['foo' => 'bar'])->shouldBeCalledTimes(1);
         $attributesProphecy->get('_format')->willReturn(null)->shouldBeCalledTimes(1);
-        $attributesProphecy->set('_api_normalization_context', ['foo' => 'bar', 'base_url' => '/api', 'api_gateway' => true])->shouldBeCalledTimes(1);
+        $attributesProphecy->set('_api_normalization_context', ['foo' => 'bar', 'base_url' => '/api', 'api_gateway' => true, 'spec_version' => '3.1.0'])->shouldBeCalledTimes(1);
 
         $documentation = new DocumentationAction($this->prophesize(ResourceNameCollectionFactoryInterface::class)->reveal(), 'my api', '', '1.0.0', $openApiFactoryProphecy->reveal());
         $this->assertInstanceOf(OpenApi::class, $documentation($requestProphecy->reveal()));
@@ -75,8 +76,9 @@ public function testDocumentationActionWithoutOpenApiFactory(): void
         $requestProphecy->query = $queryProphecy->reveal();
         $requestProphecy->getBaseUrl()->willReturn('/api')->shouldBeCalledTimes(1);
         $queryProphecy->getBoolean('api_gateway')->willReturn(true)->shouldBeCalledTimes(1);
+        $queryProphecy->get('spec_version')->willReturn('3.1.0')->shouldBeCalledTimes(1);
         $attributesProphecy->get('_api_normalization_context', [])->willReturn(['foo' => 'bar'])->shouldBeCalledTimes(1);
-        $attributesProphecy->set('_api_normalization_context', ['foo' => 'bar', 'base_url' => '/api', 'api_gateway' => true])->shouldBeCalledTimes(1);
+        $attributesProphecy->set('_api_normalization_context', ['foo' => 'bar', 'base_url' => '/api', 'api_gateway' => true, 'spec_version' => '3.1.0'])->shouldBeCalledTimes(1);
         $resourceNameCollectionFactoryProphecy = $this->prophesize(ResourceNameCollectionFactoryInterface::class);
         $resourceNameCollectionFactoryProphecy->create()->willReturn(new ResourceNameCollection(['dummies']))->shouldBeCalled();