Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for markdown table in OAS 3.0 #1413

Closed
JoeScho opened this issue Nov 14, 2017 · 4 comments
Closed

Support for markdown table in OAS 3.0 #1413

JoeScho opened this issue Nov 14, 2017 · 4 comments

Comments

@JoeScho
Copy link

JoeScho commented Nov 14, 2017

In previous versions of swagger it was possible to add tables such as:

Example Table
This Is an example table
I Would love to see them in v3.0
If This is already possible then please tell me I'm being stupid

Running the following in the Swagger editor produces different results:

this one works

openapi: 2.0.0
info:
  description: |
    Example | Table
    ----------------|-------------
    This | Is an example table 
    I | Would love to see them in v3.0
    If | This is already possible then please tell me I'm being stupid

this one doesn't work

openapi: 3.0.0
info:
  description: |
    Example | Table
    ----------------|-------------
    This | Is an example table 
    I | Would love to see them in v3.0
    If | This is already possible then please tell me I'm being stupid

It would be great to have the feature brought across into OAS 3.0

Thanks!

@MikeRalphson
Copy link
Member

MikeRalphson commented Nov 14, 2017

I believe this is a related issue swagger-api/swagger-ui#2745

OpenAPI 3.0 requires that tooling support "at a minimum" commonMark 0.27 for markdown, and tables are not part of commonMark 0.27. It is not 100% clear to me if "at a minimum" relates to the commonMark version, or any superset of commonMark 0.27.

Swagger/OpenAPI 2.0 supported GitHub-flavoured-markdown (gfm) which does support the pipe table syntax.

Depending on your specific tooling, you may need to use html <table> tags for OpenAPI 3.0 definitions.

@JoeScho
Copy link
Author

JoeScho commented Nov 14, 2017

Ok great, thanks! 👍

I'll probably just use a list for now but I'll keep my eyes peeled for any updates. I'll close this issue.

@adnnor
Copy link

adnnor commented Sep 25, 2020

Hey @JoeScho, after quite some time I have noticed that in the API global description, top of the document, under info, the GitHub flavoured table is still not working but it is working under path > [http method] > description. Although I have used HTML table under info > description, I want to know whether it could be work in the same way as others are working?

@gervaisb
Copy link

I noticed that it works everywhere when the multiline indicator is |- while it does not with >.

openapi: "3.0.0"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants