2678370f2c
* Use the resolve-refs partial as soon as possible Call it right after accessing the site.Data, since it is recursing it will solve all references in the tree. That way we don't need to wonder where to call it, we trust the validators that the refs will be used in the right place. * Enable strict $ref rule in OpenAPI validator * Document use of $ref to compose examples * Fix schema path in event-fields shortcode Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
33 lines
1.4 KiB
Markdown
33 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.
|