reverb/swagger-spec — pull request #76 by maxlinc (2014-07-29 23:01:24+00:00)
Title: Support Markup and I18N

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

```yaml
# 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

```yaml
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](https://www.transifex.com/).

```yaml
description:
format: markdown # optional - need to choose a default
translation_key: desciption_for_some_api
```