search

stripe / openapi

An OpenAPI specification for the Stripe API.
MIT License
394 stars 123 forks source link

Description fields contain HTML, should be markdown #23

Closed dflorey closed 6 years ago

dflorey commented 6 years ago

The description fields in the operations should contain markdown, but they contain HTML instead. Example:

    "/v1/application_fees/{id}/refunds": {
      "get": {
        "description": "<p>You can se... refunds.</p>",
...

See: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operationObject https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown

brandur-stripe commented 6 years ago

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.

mutsys commented 6 years ago

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

brandur-stripe commented 6 years ago

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.