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.


```
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?

87979 次浏览
小开
最佳答案

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.

小开

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>

提交答案