|
|
|
|
# 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.
|
|
|
|
|
|
|
|
|
|
## Use of `$ref` inside examples
|
|
|
|
|
|
|
|
|
|
Although the OpenAPI/JSON Schema specs only allow to use `$ref` to reference a
|
|
|
|
|
whole example, we use it to compose examples from other examples.
|
|
|
|
|
|
|
|
|
|
## Custom `x-pattern-format` key and custom formats
|
|
|
|
|
|
|
|
|
|
In JSON Schema, [`format`](https://json-schema.org/understanding-json-schema/reference/string#format)
|
|
|
|
|
is a property to convey semantic information about a schema. We define
|
|
|
|
|
`x-pattern-format` as a key on the schemas under `patternProperties` with the
|
|
|
|
|
same use as `format`, but that applies to the pattern of the property. We also
|
|
|
|
|
define custom values for formats with the `mx-` prefix in
|
|
|
|
|
`data/custom-formats.yaml`. Those values are recognized in the rendered
|
|
|
|
|
specification and link to the definition of the format.
|
|
|
|
|
|
|
|
|
|
## Custom `x-weight` key
|
|
|
|
|
|
|
|
|
|
This property allows controlling the display order of events rendered with the
|
|
|
|
|
`event-group` shortcode.
|
