From 301c7b2f07fbb74bfc533288b545805b723afddf Mon Sep 17 00:00:00 2001
From: Will <will@bootbonnet.ca>
Date: Fri, 5 Feb 2021 10:15:42 -0800
Subject: [PATCH] Restore docs describing OpenAPI extensions that we use

---
 openapi_extensions.md | 66 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 openapi_extensions.md

diff --git a/openapi_extensions.md b/openapi_extensions.md
new file mode 100644
index 000000000..b450e49f7
--- /dev/null
+++ b/openapi_extensions.md
@@ -0,0 +1,66 @@
+# OpenAPI Extensions
+
+For some functionality that is not directly provided by the OpenAPI v2
+specification, some extensions have been added that are to be consistent
+across the specification. The defined extensions are listed below. Extensions
+should not break parsers, however if extra functionality is required, aware
+parsers should be able to take advantage of the added syntax.
+
+## Using multiple files to describe API
+
+To ease API design and management, the API definition is split across several
+files. Each of these files is self-contained valid OpenAPI (except
+client-server files that become valid OpenAPI after substituting
+`%CLIENT_MAJOR_VERSION%` with `unstable` or an API release).
+
+There is no single root file in the source tree as OpenAPI requires; this file
+can be generated by `dump_swagger.py` (also doing the substitution mentioned
+above). The script does not convert the extensions described further in this
+document (`oneOf` and parameter exploding) so there can be minor
+interoperability issues with tooling that expects compliant Swagger. 
+
+## Extensible Query Parameters
+
+<!-- TODO: Remove and change instances to 'explode' after OpenAPI/Swagger v3 update -->
+
+If a unknown amount of query parameters can be added to a request, the `name`
+must be `fields...`, with the trailing ellipses representing the possibility
+of more fields.
+
+Example:
+
+```
+  - in: query
+    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:
+            ...
+```
+
+## OpenAPI 3's "2xx" format for response codes
+
+<!-- TODO: Remove this section after upgrading to OpenAPI v3 -->
+
+In some cases, the schema will have HTTP response code definitions like
+`2xx`, `3xx`, and `4xx`. These indicate that a response code within those
+ranges (`2xx` = `200` to `299`) is valid for the schema.