Clarify officially that we use multiple API files

This is not something endorsed by the OpenAPI spec, just our practice.

api/openapi_extensions.md

@@ -6,6 +6,19 @@ 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 -->