Merge pull request OAI#1049 from OAI/commonmark-descriptions

Added CommonMark support to all description

Author: Ron

versions/3.0.md

@@ -324,7 +324,7 @@ An object representing a Server.
 Field Name | Type | Description
 ---|:---:|---
 <a name="serverUrl"></a>url | `string` | **Required.** A URL to the target host.  This URL supports Server Variables and may be relative, to indicate that the host ___location is relative to the ___location where the OpenAPI definition is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
-<a name="serverDescription"></a>description | `string` | An optional string describing the host designated by the URL.
+<a name="serverDescription"></a>description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="serverVariables"></a>variables | [Server Variables Object](#serverVariablesObject) | An object holding variables for substitution in the URL template.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
@@ -389,8 +389,8 @@ An object representing a Server Variable for server URL template substituion.
 Field Name | Type | Description
 ---|:---:|---
 <a name="serverVariableEnum"></a>enum | [`string`] | An enumeration of primitive type values to be used if the substitution options are from a limited set.
-<a name="serverVariableDefault"></a>default | `string` |  **Required.** The default value to use for substitution if an alternate value is not specified, and MUST be used if an alternative value is _not_ supplied. Unlike the [Schema Object's](#schemaObject) `default`, this value MUST be provided by the consumer.
-<a name="serverVariableDescription"></a>description | `string` | An optional description for the server variable.
+<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.
+<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.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
@@ -652,7 +652,7 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="pathItemRef"></a>$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*.
 <a name="pathItemSummary"></a>summary| `string` | An optional, string summary, intended to apply to all operations in this path.
-<a name="pathItemDescription"></a>description | `string` | An optional, string description, intended to apply to all operations in this path.
+<a name="pathItemDescription"></a>description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="pathItemGet"></a>get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
 <a name="pathItemPut"></a>put | [Operation Object](#operationObject) | A definition of a PUT operation on this path.
 <a name="pathItemPost"></a>post | [Operation Object](#operationObject) | A definition of a POST operation on this path.
@@ -1910,7 +1910,7 @@ X-Rate-Limit-Reset:
 Field Name | Type | Description
 ---|:---:|---
 <a name="exampleSummary"></a>summary | `string` | Short description for the example.
-<a name="exampleDescription"></a>description | `string` | Long description for the example.
+<a name="exampleDescription"></a>description | `string` | Long description for the example. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="exampleValue"></a>value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
 <a name="exampleExternalValue"></a>externalValue | `string` | A URL that points to the literal example. This provides the ability to reference examples that cannot easily be included in JSON or YAML documents.  The `value` field and `externalValue` field are mutually exclusive. 
 
@@ -3357,7 +3357,7 @@ Supported schemes are HTTP authentication, an API key (either as a header or as
 Field Name | Type | Validity | Description
 ---|:---:|---|---
 <a name="securitySchemeType"></a>type | `string` | Any | **Required.** The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`.
-<a name="securitySchemeDescription"></a>description | `string` | Any | A short description for security scheme.
+<a name="securitySchemeDescription"></a>description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="securitySchemeName"></a>name | `string` | `apiKey` | **Required.** The name of the header or query parameter to be used.
 <a name="securitySchemeIn"></a>in | `string` | `apiKey` | **Required.** The ___location of the API key. Valid values are `"query"` or `"header"`.
 <a name="securitySchemeScheme"></a>scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC 7235](https://tools.ietf.org/html/rfc7235#section-4.2).