如何格式化 Swagger 2.0 文本描述? [英] How to format Swagger 2.0 text descriptions?

问题描述

我想格式化我的 Swagger API 描述，以便它们不是简单的文本段落.最好，我想给它添加一个小桌子.

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.

我没有在 Swagger 描述中找到有关文本格式的在线参考.如果我启动 Swagger Editor，然后打开 Instagram 示例(文件 打开示例 Instagram.yaml), 我看到 yaml 文件中的第一个描述显示了一些格式，包括超链接和边界框:

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

这看起来像标准的Markdown，但是当我在示例描述中添加表格降价时，编辑器出现错误:

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

Swagger 2.0 允许什么格式?我在渲染表格时做错了什么吗?

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

推荐答案

Swagger 编辑器支持 Markdown.下面是在 OpenAPI (Swagger) 文档中使用 Markdown 的示例:

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

您可以将上述示例复制并粘贴到 Swagger Editor 以查看输出.

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

这篇关于如何格式化 Swagger 2.0 文本描述?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！