Merge pull request #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).