Description fields contain HTML, should be markdown about openapi HOT 3 CLOSED

Yeah, I'd like to get this fixed. Unfortunately I think there's a fair bit of badly formatted docs that I need to fix, so this has always been too much for to small of a gain to be prioritized. We'll try to get to it.

from openapi.

This is not a error. The OpenAPI spec does say that GFM can be used for description attributes. GFM just extends plain Markdown, which states:

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Of course, inserting <p> elements is unnecessary but it is still valid Markdown.

See:
https://daringfireball.net/projects/markdown/syntax#html

from openapi.

Yes, exactly. For best hygiene, I'd like to have everything converted over to pure non-HTML Markdown at some point, but I don't expect to do this for a while. In the meantime, any consumers should be able to handle basic HTML as allowed by the spec.

from openapi.