Provide guidance on Markdown table syntax

[shockey]

CommonMark notably does not include table syntax, which means OpenAPI 3 document authors are limited to writing raw HTML tables.

OpenAPI tools have filled the gap by pulling in other table syntaxes - most recently Swagger UI, where I hesitantly accepted GFM table syntax support (https://github.com/swagger-api/swagger-ui/pull/5224).

It doesn't look like CommonMark is going to decide on a syntax anytime soon, and OpenAPI isn't clear about what latitude tooling authors have in going above and beyond the base CommonMark spec:

Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27.

This clause, IMO, is unclear - does this mean that a tool can support any rich text syntax on top of CM 0.27, or that only CM versions 0.27+ can be supported?

I'd like to see OpenAPI either bless a specific Markdown table syntax for use in tooling, or explicitly give tooling authors latitude in the spec to support additional Markdown syntaxes that don't conflict with CM as they see fit.

(cc #1413)

[darrelmiller]

That clause was intended to give tooling the freedom to support additional markdown syntax on top of CM 0.27. We didn't want the spec to get into the business of deciding what is considered safe or unsafe syntax to include in content. That is the responsibility of tooling.

[polarweasel]

So what's the resolution here? No updates since March. Does the spec need clarification, or should this be closed?

[handrews]

@polarweasel the resolution is clarifying what @darrelmiller said in 3.x, while using the following discussion to consider larger changes in 4.x:

• OAI/sig-moonwalk#128

[handrews]

PR merged for 3.0.4 and ported to 3.1.1 via PR #3921!