diff --git a/src/oas.md b/src/oas.md index 82a8885fa8..3c38f05e72 100644 --- a/src/oas.md +++ b/src/oas.md @@ -607,7 +607,7 @@ The path itself is still exposed to the documentation viewer but they will not k | head | [Operation Object](#operation-object) | A definition of a HEAD operation on this path. | | patch | [Operation Object](#operation-object) | A definition of a PATCH operation on this path. | | trace | [Operation Object](#operation-object) | A definition of a TRACE operation on this path. | -| query | [Operation Object](#operation-object) | A definition of a QUERY operation, as defined in the most recent IETF draft ([draft-ietf-httpbis-safe-method-w-body-08](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-11.html) as of this writing) or its RFC successor, on this path. | +| query | [Operation Object](#operation-object) | A definition of a QUERY operation, as defined in the most recent IETF draft ([draft-ietf-httpbis-safe-method-w-body-14](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-14.html) as of this writing) or its RFC successor, on this path. | | additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. The map key is the HTTP method with the same capitalization that is to be sent in the request. This map MUST NOT contain any entry for the methods that can be defined by other fixed fields with Operation Object values (e.g. no `POST` entry, as the `post` field is used for this method). | | servers | [[Server Object](#server-object)] | An alternative `servers` array to service all operations in this path. If a `servers` array is specified at the [OpenAPI Object](#oas-servers) level, it will be overridden by this value. | | parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). | @@ -788,7 +788,7 @@ The `example` and `examples` fields are mutually exclusive; see [Working with Ex | Field Name | Type | Description | | ---- | :----: | ---- | -| name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case-sensitive_. | +| name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case-sensitive_. | | in | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"querystring"`, `"header"`, `"path"` or `"cookie"`. | | description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameter-in) is `"path"`, this field is **REQUIRED** and its value MUST be `true`. Otherwise, the field MAY be included and its default value is `false`. | @@ -1605,7 +1605,7 @@ content: format: int64 - properties: event: - const: addJson + const: addJSON data: $comment: | These content fields indicate @@ -1831,9 +1831,9 @@ requestBody: # image media type(s) in the Encoding Object. type: string contentEncoding: base64url - encoding: - icon: - contentType: image/png, image/jpeg + encoding: + icon: + contentType: image/png, image/jpeg ``` Given a name of `example` and a solid red 2x2-pixel PNG for `icon`, this @@ -1851,7 +1851,7 @@ However, this is not guaranteed, so it may be more interoperable to keep the pad See [Encoding Usage and Restrictions](#encoding-usage-and-restrictions) for guidance on correlating schema properties with parts. -Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multi-part/form-data` in particular ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)). +Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multipart/form-data` in particular ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)). ##### Handling Multiple `contentType` Values @@ -2771,7 +2771,7 @@ components: content: application/linkset+json: schema: - $ref: '#/components/mediaTypes/CollectionLinks' + $ref: '#/components/schemas/CollectionLinks' ``` #### Representing the `Set-Cookie` Header @@ -2849,11 +2849,10 @@ components: explode: true examples: SetCookies: - dataValue: { - "lang": "en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT" - "foo": "bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT" - "urlSafeData": "Hello%2C%20world%21" - } + dataValue: + lang: "en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT" + foo: "bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT" + urlSafeData: "Hello%2C%20world%21" serializedValue: | lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT foo=bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT @@ -3160,7 +3159,7 @@ This means that the data form of this serialization is equivalent to the followi ```json { "code": "1234", - "count": 42 + "count": 42, "extra": { "info": "abc" } @@ -4293,14 +4292,15 @@ application/xml: name: Fluffy - kind: Dog name: Fido + externalValue: ./examples/pets.xml ``` Where `./examples/pets.xml` would be: ```xml - Fluffy - Fido + Fluffy + Fido ``` @@ -4321,15 +4321,16 @@ components: xml: nodeType: cdata responses: - content: - application/xml: - schema: - $ref: "#/components/schemas/Documentation" - examples: - docs: - dataValue: - content: Awesome Docs - externalValue: ./examples/docs.xml + AwesomeDocs: + content: + application/xml: + schema: + $ref: "#/components/schemas/Documentation" + examples: + docs: + dataValue: + content: Awesome Docs + externalValue: ./examples/docs.xml ``` Where `./examples/docs.xml` would be: