diff --git a/openapi_extensions.md b/openapi_extensions.md index eba1121c..9e833f18 100644 --- a/openapi_extensions.md +++ b/openapi_extensions.md @@ -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 @@ -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 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 - - - -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 - - - -`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 - - - -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. +the extensions described further in this document so there can be minor +interoperability issues with tooling that expects compliant OpenAPI. ## Custom `x-addedInMatrixVersion` key