Merged OpenAPI.next

Author: darrelmiller

versions/3.0.md

@@ -135,7 +135,7 @@ The object provides metadata about the API. The metadata can be used by the clie
 Field Name | Type | Description
 ---|:---:|---
 <a name="infoTitle"></a>title | `string` | **Required.** The title of the application.
-<a name="infoDescription"></a>description | `string` | A short description of the application. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
+<a name="infoDescription"></a>description | `string` | A short description of the application. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="infoTermsOfService"></a>termsOfService | `string` | A URL to the Terms of Service for the API.
 <a name="infoContact"></a>contact | [Contact Object](#contactObject) | The contact information for the exposed API.
 <a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API.
@@ -448,7 +448,7 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="operationTags"></a>tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
 <a name="operationSummary"></a>summary | `string` | A short summary of what the operation does. For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
-<a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
+<a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
 <a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [___location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters).
@@ -582,7 +582,7 @@ Allows referencing an external resource for extended documentation.
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="externalDocDescription"></a>description | `string` | A short description of the target documentation. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
+<a name="externalDocDescription"></a>description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="externalDocUrl"></a>url | `string` | **Required.** The URL for the target documentation. Value MUST be in the format of a URL.
 
 ##### Patterned Objects 
@@ -624,8 +624,13 @@ For complex parameter schemas, a serialization strategy is required. For all typ
 Field Name | Type | Description
 ---|:---:|---
 <a name="parameterName"></a>name | `string` | **Required.** The name of the parameter. Parameter names are *case sensitive*. <ul><li>If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.<li>For all other cases, the `name` corresponds to the parameter name used based on the [`in`](#parameterIn) property.</ul>
+<<<<<<< HEAD
 <a name="parameterIn"></a>in | `string` | **Required.** The ___location of the parameter. Possible values are "query", "header", "path" or "cookie".
 <a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use.  [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
+=======
+<a name="parameterIn"></a>in | `string` | **Required.** The ___location of the parameter. Possible values are "query", "header", "path", "formData" or "cookie".
+<a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use.  [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
+>>>>>>> OpenAPI.next
 <a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. 
 <a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
 <a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
@@ -753,7 +758,7 @@ The `Content-Type` of the request body must be specified by the `consumes` attri
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="requestBodyDescription"></a>description | `string` | A brief description of the request body. This could contain examples of use.  [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
+<a name="requestBodyDescription"></a>description | `string` | A brief description of the request body. This could contain examples of use.  [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="requestBodyRepresentations"></a>representations | [Representations Object](#representationsObject) | The representations of the request body.
 <a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `true`.
 
@@ -1083,7 +1088,7 @@ Describes a single response from an API Operation, including design-time, static
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="responseDescription"></a>description | `string` | **Required.** A short description of the response. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
+<a name="responseDescription"></a>description | `string` | **Required.** A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="responseHeaders"></a>headers | [Headers Object](#headersObject) | A list of headers that are sent with the response.
 <a name="responseRepresentations"></a>representations | [Representations Object](#representationsObject) | An object containing descriptions of potential response payloads.
 <a name="responseLinks"></a>links | [Links Object](#linksObject) | An object representing operations related to the response payload.
@@ -1306,7 +1311,7 @@ href        | url    | a relative or absolute URL to a linked resource. This fie
 operationId | string | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive with the `href` field.  Relative `href` values _may_ be used to locate an existing Operation Object in the OAS.
 parameters  | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
 headers     | Link Headers Object    | an Object representing headers to pass to the linked resource.
-description | string | a description of the link, supports GFM.
+description | string | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).
 ^x-         | Any    | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
 
 Locating a linked resource may be performed by either a `href` or `operationId`. In the case of an `operationId`, it must be unique and resolved in the scope of the OAS document.  Because of the potential for name clashes, consider the `href` syntax as the preferred method for specifications with external references.
@@ -1737,7 +1742,7 @@ Allows adding meta data to a single tag that is used by the [Operation Object](#
 Field Name | Type | Description
 ---|:---:|---
 <a name="tagName"></a>name | `string` | **Required.** The name of the tag.
-<a name="tagDescription"></a>description | `string` | A short description for the tag. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
+<a name="tagDescription"></a>description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="tagExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag.
 
 ##### Patterned Fields
@@ -1872,7 +1877,7 @@ The following properties are taken directly from the JSON Schema definition and
 - $ref - As a [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03)
 - format (See [Data Type Formats](#dataTypeFormat) for further details)
 - title
-- description ([GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation)
+- description ([CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation)
 - default (Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object)
 - multipleOf
 - maximum
@@ -1906,7 +1911,7 @@ Field Name | Type | Description
 <a name="schemaReadOnly"></a>readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as `readOnly` being `true` SHOULD NOT be in the `required` list of the defined schema. Default value is `false`.
 <a name="schemaXml"></a>xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property.
 <a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 
-<a name="schemaExample"></a>example | Any | A free-form property to include a an example of an instance for this schema.
+<a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema.
 <a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and should be transitioned out of usage.
 
 ##### Patterned Objects