Better guidance around summary properties

This is the second of two PRs to resolve issues discussed in PR OAI#1009

Author: earth2marsh

versions/3.0.md

@@ -657,7 +657,7 @@ The path itself is still exposed to the documentation viewer but they will not k
 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="pathItemSummary"></a>summary| `string` | A brief explanation that applies to all operations in this path. It may either complement or substitute for a description, though it is usually shorter. Only plain text is supported. 
 <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.
@@ -763,7 +763,7 @@ Describes a single API operation on a path.
 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.
+<a name="operationSummary"></a>summary | `string` | A brief explanation of what the operation does. It may either complement or substitute for a description, though it is usually shorter. Only plain text is supported. 
 <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.
@@ -1922,7 +1922,7 @@ X-Rate-Limit-Reset:
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="exampleSummary"></a>summary | `string` | Short description for the example.
+<a name="exampleSummary"></a>summary | `string` | A brief explanation of the given example. It may either complement or substitute for a description, though it is usually shorter. Only plain text is supported. 
 <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.