matrix-spec-proposals/openapi_extensions.md

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

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

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

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.