I have some Swagger-based documentation for a few APIs I've written, and I find it very frustrating because you can see in the renderers for Swagger that nobody actually documents with it. Nominally, several of the fields are specified as Markdown, allowing for useful formatting in your documentation, but what fields are actually rendered as Markdown in a given renderer is semi-random. The top-level description usually is, but a lot of the other fields come out random. In the worst cases, not only is the "Markdown" content rendered as plain text, it also is simply slapped between <p></p>, so the newlines are eliminated.