You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
34 lines
1.4 KiB
Markdown
34 lines
1.4 KiB
Markdown
# 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.
|