Skip to content

Commit 2d33542

Browse files
darrelmillerdarrelmiller
committed
Merge remote-tracking branch 'refs/remotes/origin/OpenAPI.next' into dm/operationref
2 parents ee64875 + b2b1ef6 commit 2d33542

1 file changed

Lines changed: 73 additions & 17 deletions

File tree

‎versions/3.0.md‎

Lines changed: 73 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -168,7 +168,7 @@ password | `string` | `password` | Used to hint UIs the input needs to be obscur
168168

169169
### <a name="richText"></a>Rich Text Formatting
170170
Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
171-
OpenAPI compliant tooling MUST support [CommonMark 0.27](http://spec.commonmark.org/0.27/).
171+
Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](http://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns.
172172

173173
### <a name="relativeReferences"></a>Relative References in URLs
174174

@@ -338,13 +338,39 @@ This object can be extended with [Specification Extensions](#specificationExtens
338338

339339
A single server would be described as:
340340

341+
```json
342+
{
343+
"url": "https://development.gigantic-server.com/v1",
344+
"description": "Development server"
345+
}
346+
```
347+
341348
```yaml
342349
url: https://development.gigantic-server.com/v1
343350
description: Development server
344351
```
345352

346353
The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers):
347354

355+
```json
356+
{
357+
"servers": [
358+
{
359+
"url": "https://development.gigantic-server.com/v1",
360+
"description": "Development server"
361+
},
362+
{
363+
"url": "https://staging.gigantic-server.com/v1",
364+
"description": "Staging server"
365+
},
366+
{
367+
"url": "https://api.gigantic-server.com/v1",
368+
"description": "Production server"
369+
}
370+
]
371+
}
372+
```
373+
348374
```yaml
349375
servers:
350376
- url: https://development.gigantic-server.com/v1
@@ -357,6 +383,33 @@ servers:
357383

358384
The following shows how variables can be used for a server configuration:
359385

386+
```json
387+
{
388+
"servers": [
389+
{
390+
"url": "https://{username}.gigantic-server.com:{port}/{basePath}",
391+
"description": "The production API server",
392+
"variables": {
393+
"username": {
394+
"default": "demo",
395+
"description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
396+
},
397+
"port": {
398+
"enum": [
399+
8443,
400+
443
401+
],
402+
"default": 8443
403+
},
404+
"basePath": {
405+
"default": "v2"
406+
}
407+
}
408+
}
409+
]
410+
}
411+
```
412+
360413
```yaml
361414
servers:
362415
- url: https://{username}.gigantic-server.com:{port}/{basePath}
@@ -395,7 +448,7 @@ An object representing a Server Variable for server URL template substitution.
395448
396449
Field Name | Type | Description
397450
---|:---:|---
398-
<a name="serverVariableEnum"></a>enum | [`string`] | An enumeration of primitive type values to be used if the substitution options are from a limited set.
451+
<a name="serverVariableEnum"></a>enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set.
399452
<a name="serverVariableDefault"></a>default | `string` | **Required.** The default value to use for substitution if an alternate value is not specified, and will be sent if an alternative value is _not_ supplied. Unlike the [Schema Object's](#schemaObject) `default`, this value MUST be provided by the consumer.
400453
<a name="serverVariableDescription"></a>description | `string` | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
401454

@@ -713,11 +766,13 @@ This object can be extended with [Specification Extensions](#specificationExtens
713766
"in": "path",
714767
"description": "ID of pet to use",
715768
"required": true,
716-
"type": "array",
717-
"items": {
718-
"type": "string"
769+
"schema": {
770+
"type": "array",
771+
"items": {
772+
"type": "string"
773+
}
719774
},
720-
"style": "commaDelimited"
775+
"style": "simple"
721776
}
722777
]
723778
}
@@ -748,10 +803,11 @@ parameters:
748803
in: path
749804
description: ID of pet to use
750805
required: true
751-
type: array
752-
format: form
753-
items:
754-
type: string
806+
schema:
807+
type: array
808+
style: simple
809+
items:
810+
type: string
755811
```
756812

757813
#### <a name="operationObject"></a>Operation Object
@@ -965,10 +1021,10 @@ In order to support common ways of serializing simple parameters, a set of `styl
9651021
----------- | ------ | -------- | --------
9661022
matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)
9671023
label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5)
968-
form | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value.
969-
simple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.2).
970-
spaceDelimited | `array` | `query` | Space separated array values. This option replaces `collectionFormat` equal to `ssv`.
971-
pipeDelimited | `array` | `query` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes`.
1024+
form | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.
1025+
simple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.2). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.
1026+
spaceDelimited | `array` | `query` | Space separated array values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.
1027+
pipeDelimited | `array` | `query` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.
9721028
deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.
9731029

9741030

@@ -1016,7 +1072,7 @@ A header parameter with an array of 64 bit integer numbers:
10161072
"format": "int64"
10171073
}
10181074
},
1019-
"style": "commaDelimited"
1075+
"style": "simple"
10201076
}
10211077
```
10221078

@@ -1030,7 +1086,7 @@ schema:
10301086
items:
10311087
type: integer
10321088
format: int64
1033-
style: commaDelimited
1089+
style: simple
10341090
```
10351091

10361092
A path parameter of a string value:
@@ -1575,7 +1631,7 @@ A single encoding definition applied to a single schema property.
15751631
Field Name | Type | Description
15761632
---|:---:|---
15771633
<a name="encodingContentType"></a>contentType | `string` | The Content-Type to use for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` – `application/octet-stream`; for other primitive types – `text/plain`; for `object` - `application/json`; for `array` – the default is defined based on the inner type.
1578-
<a name="encodingHeaders"></a>headers | Map[`string`, Headers Object] | A string map allowing additional information to be provided as headers, for example `Content-Disposition`. Note `Content-Type` is described separately and will be ignored from this section.
1634+
<a name="encodingHeaders"></a>headers | Map[`string`, [Header Object](#headerObject)] | A string map allowing additional information to be provided as headers, for example `Content-Disposition`. Note `Content-Type` is described separately and will be ignored from this section.
15791635
<a name="encodingStyle"></a>style | `string` | Describes how a specific property value will be serialized depending on its type . See [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property. The behavior follows the same values allowed for `query` parameters, including default values.
15801636
<a name="encodingExplode"></a>explode | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
15811637
<a name="encodingAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`.

0 commit comments

Comments
 (0)