Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-26 13:04:10 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Update OpenAPI Extensions for OpenAPI 3.1

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2023-09-12 12:15:04 +02:00
parent 838dec272c
commit bae676da70
No known key found for this signature in database
GPG key ID: 29A48C1F03620416
1 changed files with 3 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
openapi_extensions.md
View file

@ -1,6 +1,6 @@
# OpenAPI Extensions # OpenAPI Extensions
For some functionality that is not directly provided by the OpenAPI v2 For some functionality that is not directly provided by the OpenAPI v3.1
specification, some extensions have been added that are to be consistent specification, some extensions have been added that are to be consistent
across the specification. The defined extensions are listed below. Extensions across the specification. The defined extensions are listed below. Extensions
should not break parsers, however if extra functionality is required, aware should not break parsers, however if extra functionality is required, aware
@ -13,55 +13,8 @@ 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 There is no single root file in the source tree as OpenAPI requires; this file
can be generated by `dump-swagger.py`. The script does not convert can be generated by `dump-swagger.py`. The script does not convert
the extensions described further in this document (`oneOf` and parameter the extensions described further in this document so there can be minor
exploding) so there can be minor interoperability issues with tooling that interoperability issues with tooling that expects compliant OpenAPI.
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.
## Custom `x-addedInMatrixVersion` key ## Custom `x-addedInMatrixVersion` key