如何使用OpenAPI的JSON绘制表格

Question

我想在JSON文件中制作一个表格

• 我使用 Swagger UI （2.0） 来描述 API。opneapi.json托管在Gitlab中。
• Swagger Spec说GFM语法可用于富文本表示。
• 表的 Gitlab 风味 Markdown （GFM） 语法包括“回车”。
• 但是 JSON 不处理“回车”。

是否有任何解决方法可以在openapi.json中包含表？

Answer 1

OpenAPI 2.0使用GitHub风味Markoff，它支持表的常用Markoff语法，例如：

| One | Two | Three |
|-----|-----|-------|
| a   | b   | c     |

（取自此答案的示例）

在JSON中，您可以这样写:

// JSON example
"description": "Sample table:\n\n| One | Two | Three |\n|-----|-----|-------|\n| a   | b   | c     |"

正确使用 JSON 的最简单方法是使用 http://editor.swagger.io 格式化和预览文本，然后将定义下载为 JSON。

在YAML，确保缩进是正确的(多行文本中的所有行都需要根据键名进行缩进):

# YAML example
swagger: '2.0'
info:
  version: 0.0.0
  title: Table demo
  description: |
    Sample table:

    | One | Two | Three |
    |-----|-----|-------|
    | a   | b   | c     |
paths: {}

OpenAPI 3.0规范规定工具必须至少支持CommonMark v. 0.27，并且可能支持CommonMark之上的其他Markdown语法。

CommonMark本身没有表语法，但是您可以使用HTML

javascript prettyprint-override">// JSON example
"description": "Sample table:\n\n<table><tr><td>One</td><td>Two</td><td>Three</td></tr><tr><td>a</td><td>b</td><td>c</td></tr></table>"

在YAML:

openapi: 3.0.0
info:
  version: 0.0.0
  title: Table demo
  description: |
    Sample table:

    <table>
      <tr>
        <td>One</td>
        <td>Two</td>
        <td>Three</td>
      </tr>
      <tr>
        <td>a</td>
        <td>b</td>
        <td>c</td>
      </tr>
    </table>
paths: {}


这就是说，Swagger UI版本3.22.0和Swagger Editor版本3.6.27支持OAS3的GFM表语法（除了CommonMark之外），因此这些工具的用户可以使用熟悉的Markdown表语法：

# Works in Swagger UI and Swagger Editor
openapi: 3.0.0
info:
  version: 0.0.0
  title: Table demo
  description: |
    Sample table:

    | One | Two | Three |
    |-----|-----|-------|
    | a   | b   | c     |
paths: {}