|
|
|
|
# OpenAPI Extensions
|
|
|
|
|
|
|
|
|
|
For some functionality that is not directly provided by the OpenAPI v3.1
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
There is no single root file in the source tree as OpenAPI requires; this file
|
|
|
|
|
can be generated by `dump-openapi.py`. The script does not convert
|
|
|
|
|
the extensions described further in this document so there can be minor
|
|
|
|
|
interoperability issues with tooling that expects compliant OpenAPI.
|
|
|
|
|
|
|
|
|
|
## Custom `x-addedInMatrixVersion` key
|
|
|
|
|
|
|
|
|
|
This property is added throughout the OpenAPI schemas to denote which version
|
|
|
|
|
of the Matrix specification added the associated object (endpoint, parameter,
|
|
|
|
|
property, etc).
|
|
|
|
|
|
|
|
|
|
## Custom `x-changedInMatrixVersion` key
|
|
|
|
|
|
|
|
|
|
A variation of the above: indicates changes to the associated parameter in
|
|
|
|
|
particular Matrix specification versions.
|
