Replace HTML with markdown

[rbren]

https://github.com/domchristie/to-markdown

HTML tends to show up in api.info.description, parameter.description, etc

[IvanGoncharov]

According to Swagger 2.0 spec:

A short description of the application. GFM syntax can be used for rich text representation.

And GFM support subset of html.

But I agree that HTML support unnecessarily complicate client side and if possible should be converted.
I will review this tool and if it provides accurate conversion than I will use it.

[MikeRalphson]

Most tools rendering Markdown will use a markdown-to-html converter where the embedded html will be passed-through. All OpenAPI 2/3 compatible tools will need to support html in descriptions, so I don't think we would be achieving much by this.

Please shout if there is a markdown-to-text use-case which doesn't support HTML.