From b41eb26124de0f5c6b54fba4a9cb3939fb10adfe Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Sun, 12 Aug 2018 16:52:07 +0900
Subject: [PATCH] Document OpenAPI extension

Signed-off-by: Alexey Rusakov <Alexey.Rusakov@pm.me>
---
 api/openapi_extensions.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/api/openapi_extensions.md b/api/openapi_extensions.md
index 9f4745fd..339452ba 100644
--- a/api/openapi_extensions.md
+++ b/api/openapi_extensions.md
@@ -21,3 +21,25 @@ Example:
     name: fields...
     type: string
 ```
+
+## Using oneOf to provide type alternatives
+
+<!-- TODO: Remove this section after upgrading to OpenAPI v3 -->
+
+`oneOf` (available in JSON Schema and Swagger/OpenAPI v3 but not in v2)
+is used in cases when a simpler type specification as a list of types
+doesn't work, as in the following example:
+```
+  properties:
+    old: # compliant with old Swagger
+      type:
+        - string
+        - object # Cannot specify a schema here
+    new: # uses oneOf extension
+      oneOf:
+        - type: string
+        - type: object
+          title: CustomSchemaForTheWin
+          properties:
+            ...
+```