00c6a866e2
Historical note: this was originally a series of several commits, spread out over several weeks. They have been squashed together to make `git annotate` work properly. The original commits were: * 91ab3934 <Will> 2021-01-25 21:16:42 -0800 Add raw API end event schemas into /data directory * aae22f47 <Will> 2021-01-25 21:33:06 -0800 Remove non-data files * 1092d4ca <Will> 2021-01-26 20:41:33 -0800 Add data-compatiuble extension (.yaml) to all data files that currently omit one * 21060109 <Will> 2021-01-26 20:57:28 -0800 Remove symlink to event-schemas, and update openAPI schema paths accordingly * 4f633845 <Travis Ralston> 2021-04-12 21:54:54 -0600 Fix event schema examples too * 301c7b2f <Will> 2021-02-05 10:15:42 -0800 Restore docs describing OpenAPI extensions that we use
66 lines
2.3 KiB
Markdown
66 lines
2.3 KiB
Markdown
# OpenAPI Extensions
|
|
|
|
For some functionality that is not directly provided by the OpenAPI v2
|
|
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 (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 -->
|
|
|
|
If a unknown amount of query parameters can be added to a request, the `name`
|
|
must be `fields...`, with the trailing ellipses representing the possibility
|
|
of more fields.
|
|
|
|
Example:
|
|
|
|
```
|
|
- in: query
|
|
name: fields...
|
|
type: string
|
|
```
|
|
|
|
## Using oneOf to provide type alternatives
|
|
|
|
<!-- TODO: Remove this section after upgrading to OpenAPI v3 -->
|
|
|
|
`oneOf` (available in JSON Schema and Swagger/OpenAPI v3 but not in v2)
|
|
is used in cases when a simpler type specification as a list of types
|
|
doesn't work, as in the following example:
|
|
```
|
|
properties:
|
|
old: # compliant with old Swagger
|
|
type:
|
|
- string
|
|
- object # Cannot specify a schema here
|
|
new: # uses oneOf extension
|
|
oneOf:
|
|
- type: string
|
|
- type: object
|
|
title: CustomSchemaForTheWin
|
|
properties:
|
|
...
|
|
```
|
|
|
|
## OpenAPI 3's "2xx" format for response codes
|
|
|
|
<!-- TODO: Remove this section after upgrading to OpenAPI v3 -->
|
|
|
|
In some cases, the schema will have HTTP response code definitions like
|
|
`2xx`, `3xx`, and `4xx`. These indicate that a response code within those
|
|
ranges (`2xx` = `200` to `299`) is valid for the schema.
|