3.0.md description field cleanup

[curtisr7]

While reviewing the spec, I've found some inconsistencies in regards to which of the various description fields allow markdown syntax. It seems some do, some done and I don't really see a pattern. For the sake of consistency does it make sense that we allow markdown for all description fields? The other thing that jumps out at me is that some descriptions state that they should be short, others verbose. Is that an artifact of the author of a given section, or has there been some thought put into?

Along those same lines, should we allow markdown for all summery and fields? (Perhaps some others)

Let me know if this seems reasonable and I can get a PR rolling.

Example:
info.description : A short description of the application. CommonMark syntax can be used for rich text representation.
server.description : An optional string describing the host designated by the URL.
templates.description : An optional description for the template parameter
path.description : An optional, string description, intended to apply to all operations in this path.
operation.description : A verbose explanation of the operation behavior. CommonMark syntax can be used for rich text representation.
externalDocumentation.description : A short description of the target documentation. CommonMark syntax can be used for rich text representation.
parameter.description : A brief description of the parameter. This could contain examples of use. CommonMark syntax can be used for rich text representation.
....

[darrelmiller]

I believe all the description fields should indicate support for markdown. @OAI/tdc Thoughts?

[DavidBiesack]

Yup. Markdown is supported/expected for all description strings. Paths and operations should have a brief summary, then a fuller description. parameters have only a description; I don't know if it is worth adding summary there for consistency; it's not clear where we would need both for parameters.

In schema definitions, JSON schema provides title (instead of summary) and description, However, JSON Schema is mute on the syntax of these strings.

The current Swagger UI applies Markdown processing to summary text as well as to schema description (but I don't think it renders the schema title??), so I believe the note that CommonMark applies there should be added to the 3.0 spec. (I do not think we intend to remove support for Markdown in 3.0)

[webron]

Yes, description should support markdown everywhere.
The only place I recall that suggests being short is summary for operations.
I don't see title as equivalent to summary.

[komikoni]

Below is a summary of GFM of explanation part
(I am sorry for the Japanese document)

http://www.slideshare.net/KeisukeKonishi/swaggerapi-64300306/34

http://www.slideshare.net/KeisukeKonishi/swaggerapi-64300306/35

http://www.slideshare.net/KeisukeKonishi/swaggerapi-64300306/36

[komikoni]

Below is a summary of GFM of explanation part
in english

common-spec

title	JSON pointer	OAI-spec2	Editor-impl	UI-imple	description
Application title	#/info/title	text	OK	OK
Application description	#/info/description	GFM	OK	OK	A description of the whole application is given here.
Extended document resources	#/externalDocs/description	GFM	OK	NG(only-text)	The Editor displays GFM, and the whole URL links. UI does not interpret GFM
Security method name	#/securityDefinition/{name}/description	text	OK	OK	The Editor is always displayed on the screen, the UI is not normally displayed, it is displayed on the pop-up modal screen when the authorization button is pressed
Scope name of OAuth 2	#/securityDefinition/{name}/scopes/{name}	text	OK	OK	Same as above
Explanation of tags grouping resource operations	#/tags/0/description	GFM	NG(only-text)	NG(only-text)	Neither Editor nor UI interprets GFM.
Extended document resources	#/tags/0/externalDocs/description	GFM	NG(non-display)	NG(non-display)	Editor and UI are not displayed

request-spec

title	JSON pointer　（basepath #/paths/{path}）	OAI-spec2	Editor-impl	UI-imple	description
Resource operation overview	/{method}/summary	text	OK	OK
Description of resource operation	/{method}/description	GFM	OK	OK
Extended document operation for resource operation	/{method}/externalDocs/description	GFM	NG(non-display)	NG(non-display)	Neither UI nor Editor is displayed.
Descriptions of URI unit parameters	/parameters/0/description /{method}/parameters/0/description	GFM	NG(only-text)	NG(only-text)	Neither Editor nor UI interprets GFM.
Title of schema	/parameters/0/schema/title /{method}/parameters/0/schema/title	text	OK	OK
Description of schema	/parameters/0/schema/description /{method}/parameters/0/schema/description	GFM	NG(only-text)	NG(non-display)	In the Editor, GFM interpretation is not done but it is displayed. It is not displayed in the UI. (In JSONEditer, GMF is not interpreted but displayed)
Schema extension document Description	/parameters/0/schema/externalDocs/description /{method}/parameters/0/schema/externalDocs/description	GFM	NG(non-display)	NG(non-display)	Neither UI nor Editor is displayed.
Title of property item	/parameters/0/schema/properties/{property}/title /{method}/parameters/0/schema/properties/{property}/title	text	OK	OK
Property item description	/parameters/0/schema/properties/{property}/description /{method}/parameters/0/schema/properties/{property}/description	GFM	NG(only-text)	NG(non-display)	In the Editor, GFM interpretation is not done but it is displayed. It is not displayed in the UI. (In JSON Editor, GMF is not interpreted but it is displayed)

response-spec

title	JSON pointer　（basepath #/paths/{path}）	OAI-spec2	Editor-impl	UI-imple	description
Explanation of the response of the status code unit	/{method}/responses/{StatusCode}/description	GFM	OK	OK
Description of the heder	/{method}/responses/{StatusCode}/headers/{headerName}/description	text	OK	OK	The description of the Header object is not GFM. Both UI and Editer do not interpret GFM.
Schema title	/{method}/responses/{StatusCode}/schema/title	text	OK	OK
Schema description	/{method}/responses/{StatusCode}/schema/description	GFM	NG(only-text)	NG(non-display)	In the Editor, GFM interpretation is not done but it is displayed. It is not displayed in the UI.
Schema extension document Description	/{method}/responses/{StatusCode}/schema/externalDocs/description	GFM	NG(non-display)	NG(non-display)	Neither UI nor Editor is displayed.
Title of property item	/{method}/responses/{StatusCode}/schema/properties/{property}/title	text	OK	OK
Property Item Description	/{method}/responses/{StatusCode}/schema/properties/{property}/description	GFM	NG(only-text)	OK	In the Editor, GFM interpretation is not done but it is displayed. In the UI, GFM is displayed.