From 67a8176903e8361310c32a7b0559f3adc504012d Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Thu, 28 May 2020 13:54:36 +0200 Subject: [PATCH] Clarify officially that we use multiple API files This is not something endorsed by the OpenAPI spec, just our practice. --- api/openapi_extensions.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/api/openapi_extensions.md b/api/openapi_extensions.md index 339452ba..c614793d 100644 --- a/api/openapi_extensions.md +++ b/api/openapi_extensions.md @@ -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