Support Markup and I18N

[maxlinc]

This is an alternate proposal to simply defining the "description" field as being Markdown. I did this quickly via the GitHub editor, but if it looks good it could be cleaned up with:

• Default values
• Make a reusable definition for "documentation" in case we want to use it for summary or any other sections.

This PR allows:

A simple string description

# Note: We need to decide what the default is if only a string is given... plaintext? HTML? Markdown?
description: |
  The description can be a simple string
  with or without newlines.

Explicitly selecting a markup format

description:
  format: markdown # optional - need to choose a default 
  content: |
    The description could also have an explicit format and content section, so it can
    use things like [http://daringfireball.net/projects/markdown/](http://daringfireball.net/projects/markdown/)
    or perhaps other supported markup languages like [asciidoc](http://www.methods.co.nz/asciidoc/)

The use of translation keys

This could allow Swagger-UI to be hooked up to translation tools or services like Transifex.

description:
  format: markdown # optional - need to choose a default
  translation_key: description_for_some_api

[maxlinc]

I am worried this could be a bit tricky for implementors to parse. I know how I'd do it in Ruby but I'm not sure about other Swagger implementors.

[fehguy]

I don't think parsing will be the problem, but we do need to support JSON.

A literal translation of:

description: |
  The description can be a simple string
  with or without newlines.

is

{
  "description": "The description can be a simple string\nwith or without newlines.\n"
}

[maxlinc]

Those all support JSON as well. I wrote in YAML because it looks nicer and allows comments* :)

This should be much less likely to have any JSON vs YAML issues than the current Swagger-Editor behavior, because it is based on the presence or absence of the "format" parameter, rather than the presence or absence of newlines -- which may be confusing when converting between different JSON and YAML string formats.

Note: *some JSON parsers ignore comments and Douglas Crockford said this, but JSON does not officially allow comments.

[mohsen1]

I like this. There should be a way to set format globally too

[Bradamant3]

Docs girl here, and I like it too. But I'll add what someone put into the email thread -- only in the description field. Not summary, not title, not operationID, not any other string. This might be getting into the gray area between spec and implementation, but I'll come down on the side of the spec needing it.

[maxlinc]

@mohsen1 good point that format could be set globally. What if it was only set globally, rather than supporting a format on each description?

I expect that different organizations will want to use different markup languages, but I don't think as many organizations would want to mix AsciiDoc and Markdown (or whatever) in the same document.