Conditionally fall back to JSON-Schema compatible with Swagger/OpenAPI v2

OpenAPI V2 has no way to generate accurate nullable types, so we
need to disable nullable `oneOf` syntax in JSON-Schema by providing
some context to the `TypeFactory` when not operating under OpenAPI
v3 or newer considerations.

In future, Swagger/OpenAPIV2 will (finally) at some point disappear, so
we will be able to get rid of these conditionals once that happens.

Author: Ocramius

SchemaFactory.php

@@ -258,19 +258,19 @@ private function getMetadata(string $className, string $type = Schema::TYPE_OUTP
 
         return [
             $resourceMetadata,
-            $serializerContext ?? $this->getSerializerContext($resourceMetadata, $type, $operationType, $operationName),
+            $this->getSerializerContext($resourceMetadata, $type, $operationType, $operationName, $serializerContext),
             $inputOrOutput['class'],
         ];
     }
 
-    private function getSerializerContext(ResourceMetadata $resourceMetadata, string $type = Schema::TYPE_OUTPUT, ?string $operationType, ?string $operationName): array
+    private function getSerializerContext(ResourceMetadata $resourceMetadata, string $type = Schema::TYPE_OUTPUT, ?string $operationType, ?string $operationName, ?array $previousSerializerContext): array
     {
         $attribute = Schema::TYPE_OUTPUT === $type ? 'normalization_context' : 'denormalization_context';
 
         if (null === $operationType || null === $operationName) {
-            return $resourceMetadata->getAttribute($attribute, []);
+            return array_merge($resourceMetadata->getAttribute($attribute, []), (array) $previousSerializerContext);
         }
 
-        return $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, $attribute, [], true);
+        return array_merge($resourceMetadata->getTypedOperationAttribute($operationType, $operationName, $attribute, [], true), (array) $previousSerializerContext);
     }
 }

TypeFactory.php

@@ -27,6 +27,19 @@
  */
 final class TypeFactory implements TypeFactoryInterface
 {
+    /**
+     * This constant is to be provided as serializer context key to conditionally enable types to be generated in
+     * a format that is compatible with OpenAPI specifications **PREVIOUS** to 3.0.
+     *
+     * Without this flag being set, the generated format will only be compatible with Swagger 3.0 or newer.
+     *
+     * Once support for OpenAPI < 3.0 is gone, this constant **WILL BE REMOVED**
+     *
+     * @internal Once support for OpenAPI < 3.0 is gone, this constant **WILL BE REMOVED** - do not rely on
+     *           it in downstream projects!
+     */
+    public const CONTEXT_SERIALIZATION_FORMAT_OPENAPI_PRE_V3_0 = self::class.'::CONTEXT_SERIALIZATION_FORMAT_OPENAPI_PRE_V3_0';
+
     use ResourceClassInfoTrait;
 
     /**
@@ -60,7 +73,8 @@ public function getType(Type $type, string $format = 'json', ?bool $readableLink
                         'type' => 'object',
                         'additionalProperties' => $this->getType($subType, $format, $readableLink, $serializerContext, $schema),
                     ],
-                    $type
+                    $type,
+                    (array) $serializerContext
                 );
             }
 
@@ -69,13 +83,15 @@ public function getType(Type $type, string $format = 'json', ?bool $readableLink
                     'type' => 'array',
                     'items' => $this->getType($subType, $format, $readableLink, $serializerContext, $schema),
                 ],
-                $type
+                $type,
+                (array) $serializerContext
             );
         }
 
         return $this->addNullabilityToTypeDefinition(
             $this->makeBasicType($type, $format, $readableLink, $serializerContext, $schema),
-            $type
+            $type,
+            (array) $serializerContext
         );
     }
 
@@ -98,7 +114,7 @@ private function makeBasicType(Type $type, string $format = 'json', ?bool $reada
     /**
      * Gets the JSON Schema document which specifies the data type corresponding to the given PHP class, and recursively adds needed new schema to the current schema if provided.
      */
-    private function getClassType(?string $className, string $format = 'json', ?bool $readableLink = null, ?array $serializerContext = null, ?Schema $schema = null): array
+    private function getClassType(?string $className, string $format, ?bool $readableLink, ?array $serializerContext, ?Schema $schema): array
     {
         if (null === $className) {
             return ['type' => 'object'];
@@ -154,8 +170,12 @@ private function getClassType(?string $className, string $format = 'json', ?bool
      *
      * @return array<string, mixed>
      */
-    private function addNullabilityToTypeDefinition(array $jsonSchema, Type $type): array
+    private function addNullabilityToTypeDefinition(array $jsonSchema, Type $type, array $serializerContext): array
     {
+        if (\array_key_exists(self::CONTEXT_SERIALIZATION_FORMAT_OPENAPI_PRE_V3_0, $serializerContext)) {
+            return $jsonSchema;
+        }
+
         if (!$type->isNullable()) {
             return $jsonSchema;
         }