fix(OpenApiType): Wrap $ref in allOf to allow nullable

Signed-off-by: provokateurin <[email protected]>

Author: provokateurin

src/OpenApiType.php

@@ -265,6 +265,13 @@ public static function resolve(string $context, array $definitions, ParamTagValu
 
 		if ($node instanceof NullableTypeNode || $node instanceof NullableType) {
 			$type = self::resolve($context, $definitions, $node->type);
+			if ($type->ref !== null) {
+				// https://github.com/OAI/OpenAPI-Specification/issues/1368#issuecomment-354037150
+				$type = new OpenApiType(
+					$context,
+					allOf: [$type],
+				);
+			}
 			$type->nullable = true;
 			return $type;
 		}
@@ -336,6 +343,13 @@ enum: $values,
 
 			if (count($items) == 1) {
 				$type = $items[0];
+				if ($type->ref !== null) {
+					// https://github.com/OAI/OpenAPI-Specification/issues/1368#issuecomment-354037150
+					$type = new OpenApiType(
+						$context,
+						allOf: [$type],
+					);
+				}
 				$type->nullable = $nullable;
 				return $type;
 			}

tests/lib/ResponseDefinitions.php

@@ -63,6 +63,9 @@
  *     // A comment.
  *     // Another comment.
  *     multipleComments: string,
+ *     ref1: ?NotificationsPushDevice,
+ *     ref2: null|NotificationsPushDevice,
+ *     ref3: string|null|NotificationsPushDevice,
  * }
  */
 class ResponseDefinitions {

tests/openapi-full.json

@@ -256,7 +256,10 @@
                 "required": [
                     "publicKey",
                     "signature",
-                    "multipleComments"
+                    "multipleComments",
+                    "ref1",
+                    "ref2",
+                    "ref3"
                 ],
                 "properties": {
                     "publicKey": {
@@ -270,6 +273,33 @@
                     "multipleComments": {
                         "type": "string",
                         "description": "A comment. Another comment."
+                    },
+                    "ref1": {
+                        "nullable": true,
+                        "allOf": [
+                            {
+                                "$ref": "#/components/schemas/PushDevice"
+                            }
+                        ]
+                    },
+                    "ref2": {
+                        "nullable": true,
+                        "allOf": [
+                            {
+                                "$ref": "#/components/schemas/PushDevice"
+                            }
+                        ]
+                    },
+                    "ref3": {
+                        "nullable": true,
+                        "anyOf": [
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "$ref": "#/components/schemas/PushDevice"
+                            }
+                        ]
                     }
                 }
             }

tests/openapi.json

@@ -218,12 +218,48 @@
                     }
                 }
             },
+            "PushDevice": {
+                "allOf": [
+                    {
+                        "$ref": "#/components/schemas/PushDeviceBase"
+                    },
+                    {
+                        "type": "object",
+                        "required": [
+                            "publicKey",
+                            "signature"
+                        ],
+                        "properties": {
+                            "publicKey": {
+                                "type": "string"
+                            },
+                            "signature": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                ]
+            },
+            "PushDeviceBase": {
+                "type": "object",
+                "required": [
+                    "deviceIdentifier"
+                ],
+                "properties": {
+                    "deviceIdentifier": {
+                        "type": "string"
+                    }
+                }
+            },
             "RequestProperty": {
                 "type": "object",
                 "required": [
                     "publicKey",
                     "signature",
-                    "multipleComments"
+                    "multipleComments",
+                    "ref1",
+                    "ref2",
+                    "ref3"
                 ],
                 "properties": {
                     "publicKey": {
@@ -237,6 +273,33 @@
                     "multipleComments": {
                         "type": "string",
                         "description": "A comment. Another comment."
+                    },
+                    "ref1": {
+                        "nullable": true,
+                        "allOf": [
+                            {
+                                "$ref": "#/components/schemas/PushDevice"
+                            }
+                        ]
+                    },
+                    "ref2": {
+                        "nullable": true,
+                        "allOf": [
+                            {
+                                "$ref": "#/components/schemas/PushDevice"
+                            }
+                        ]
+                    },
+                    "ref3": {
+                        "nullable": true,
+                        "anyOf": [
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "$ref": "#/components/schemas/PushDevice"
+                            }
+                        ]
                     }
                 }
             }