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

Replace all mentions of Swagger by OpenAPI (#1633)

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2023-09-19 19:26:07 +02:00 • committed by GitHub
parent df3f0af5d4
commit 99e2ff4927
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 40 additions and 87 deletions
Download patch file Download diff file Expand all files Collapse all files

55
openapi_extensions.md
View file

@ -1,6 +1,6 @@
# 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
across the specification. The defined extensions are listed below. Extensions
should not break parsers, however if extra functionality is required, aware
@ -12,56 +12,9 @@ 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-swagger.py`. 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.
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