如何使用 JSON for OpenAPI 绘制表格

Question

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

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

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

Answer 1

开放API 2.0

OpenAPI 2.0 使用 GitHub Flavored Markdown，它支持表的常用 Markdown 语法，例如：

| 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 中，确保缩进正确（多行文本中的所有行都需要与键名相关的缩进）：

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

开放API 3.0

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

CommonMark 本身没有表格语法，但您可以使用 HTML<table>元素作为解决方法：

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

在 YAML 中：

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

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

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

// 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>"