How to format Swagger 2.0 text descriptions?
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.
TERACytE
Updated on July 05, 2022Comments
-
TERACytE almost 2 years
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?
-
TERACytE over 7 yearsAh. I know why. YAML is sensitive to indentation. I did not do it correctly. Thanx Wilson.
-
Stephen McFarland almost 7 years@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!
-
fallenprogrammr almost 7 years@Stephen McFarland - The description should have " |" as its first line, and the text that you want in the description should be indented.
-
Bugs almost 7 years@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. Thought I'd be nice and pass the message on before their "answer" is removed.
-
Elliott Beach over 6 yearsSo you can't follow actually follow rendered links in the UI. Nice.
-
Shrikant Prabhu over 4 yearsHow to write such a document using springFox docket for swagger in java? We generate swagger documentation from java code using springFox[springfox.github.io/springfox/docs/snapshot/#introduction], it allows to only support string values
-
Shrikant Prabhu over 4 yearsnever mind..springfox docket supports html syntax , so I could generate list using following code (not complete code)
.description("This api page supports following operations: <ul><li>first item </li><li>second item</li></ul>"
like so.