TERACytE TERACytE - 18 days ago 4x
Markdown Question

How to format Swagger 2.0 text descriptions?

I would like to format my Swagger API descriptions so that they are not simple paragraphs of text. Preferably, I'd like to add a small table to it.

I did not find an online reference about text formatting in Swagger descriptions. If I launch the Swagger Editor, and open the Instagram example (File \ Open Example \ Instagram.yaml), I see the the first description in the yaml file shows some formatting including a hyperlink and bounding box:

[registered your client](http://instagram.com/developer/register/) it's easy
to start requesting data from Instagram.


This looks like standard Markdown, but when I add a table markdown to the samples description, the editor presents an error:


YAML Syntax Error
End of the stream or a document separator is expected at line 36, column

What formatting does Swagger 2.0 allow?
Am I doing something wrong to render a table?


Markdown is supported in swagger-editor and following is an example using Markdown in swagger document:

swagger: '2.0'
  version: 0.0.0
  title: Markdown 
  description: |
    # Heading

    Text attributes _italic_, *italic*, __bold__, **bold**, `monospace`.

    Horizontal rule:


    Bullet list:

      * apples
      * oranges
      * pears

    Numbered list:

      1. apples
      2. oranges
      3. pears

    A [link](http://example.com).


    | Column1 | Collumn2 |
    | ------- | -------- |
    | cell1   | cell2    |
          description: OK

You can copy and paste the above example to swagger-editor to see the output.