json - 如何使用 JSON for OpenAPI 绘制表格

Question

我要制作 JSON 文件中的表

我使用 Swagger UI (2.0) 来描述 API。 opneapi.json 托管在 Gitlab 中。

Swagger 规范说 GFM 语法可用于富文本表示。

表格的 Gitlab flavor Markdown (GFM) 语法包括“回车”。

但是 JSON 不处理“回车”。

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

Answer 1

开放API 2.0

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

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

(示例取自 this answer )

在 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: {}

开放API 3.0

OpenAPI 3.0 规范 states that工具必须至少支持 CommonMark v. 0.27+ ，并且可能在 CommonMark 之上支持额外的 Markdown 语法。

CommonMark 本身 does not have table syntax ，但您可以使用 HTML <table>元素作为解决方法:

// 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 v. 3.22.0+ 和 Swagger 编辑器 v. 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: {}