wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Clarify officially that we use multiple API files

Browse source 
This is not something endorsed by the OpenAPI spec, just our practice.
This commit is contained in:
Kitsune Ral 2020-05-28 13:54:36 +02:00
parent 6cfb94562e
commit 67a8176903
1 changed files with 13 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

13
api/openapi_extensions.md
View file

@ -6,6 +6,19 @@ 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
<!-- TODO: Remove and change instances to 'explode' after OpenAPI/Swagger v3 update -->