How to format Swagger 2.0 text descriptions?

Question

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.

```
  https://api.instagram.com/v1/media/popular?client_id=CLIENT-ID
```

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

|Col1|Col2|
|------|------|
|1|2|


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?

score 188 · Accepted Answer · edited Feb 11 '20 at 21:43

188

Markdown is supported in the Swagger Editor. Below is an example of using Markdown in an OpenAPI (Swagger) document:

swagger: '2.0'
info:
  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).

    An image:
    ![Swagger logo](https://raw.githubusercontent.com/swagger-api/swagger-ui/master/dist/favicon-32x32.png)

    Code block:

    ```
    {
      "message": "Hello, world!"
    }
    ```

    Tables:

    | Column1 | Column2 |
    | ------- | --------|
    | cell1   | cell2   |
paths:
  /:
    get:
      responses:
        200:
          description: OK

You can copy and paste the above example to the Swagger Editor to see the output.

edited Feb 11 '20 at 21:43

marc_s

732,580
175
1,330
1,459

answered Oct 08 '16 at 05:42

Wilson

11,339
2
29
33

6

Ah. I know why. YAML is sensitive to indentation. I did not do it correctly. Thanx Wilson. – TERACytE Oct 08 '16 at 14:30
1

@Wilson, is this markdown support limited to only the Info section? When I copy / paste this as a description for a Pet object, it does not appear the same as when it is inserted in the info section. Thanks! – Stephen McFarland May 25 '17 at 23:36
3

_@Stephen McFarland - The description should have " |" as its first line, and the text that you want in the description should be indented. Sorry I could not comment as I do not have 50 rep yet._ Posted as an answer by [fallenprogrammr](https://stackoverflow.com/users/438546/fallenprogrammr). Thought I'd be nice and pass the message on before their "answer" is removed. – Bugs May 26 '17 at 16:27
2

@Stephen McFarland - The description should have " |" as its first line, and the text that you want in the description should be indented. – fallenprogrammr May 26 '17 at 16:24
1

So you can't follow actually follow rendered links in the UI. Nice. – Elliott Beach Oct 16 '17 at 03:48
How to write such a document using springFox docket for swagger in java? We generate swagger documentation from java code using springFox[https://springfox.github.io/springfox/docs/snapshot/#introduction], it allows to only support string values – Shrikant Prabhu Sep 26 '19 at 03:44
never mind..springfox docket supports html syntax , so I could generate list using following code (not complete code) ```.description("This api page supports following operations:
- first item
- second item
"``` like so.
– Shrikant Prabhu Sep 26 '19 at 04:12

score 0 · Answer 2 · answered Nov 08 '22 at 18:40

In Swagger 3 you can also include any HTML markup in the description field, including images, not sure if it works for Swagger 2

  description: >-
    <a href="https://www.electoral-vote.com"><img border="0"
    src="https://www.electoral-vote.com/evp2022/Icons/evmap.png"
    alt="Click for www.electoral-vote.com" width="150" height="180" /></a>

How to format Swagger 2.0 text descriptions?

2 Answers2

Linked