如何使用JSON for OpenAPI绘制表格 [英] How to draw tables using JSON for OpenAPI

问题描述

我想在JSON文件中建立表

I want to make a table in a JSON file

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

在openapi.json中是否包含任何解决方法?

Is there any workaround to include tables in an openapi.json?

推荐答案

OpenAPI 2.0

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

OpenAPI 2.0

OpenAPI 2.0 uses GitHub Flavored Markdown, which supports the usual Markdown syntax for tables, such as:

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

(示例取自此答案)

在JSON中，您可以这样写:

In JSON, you would write this as:

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

获得JSON权利的最简单方法是使用 http://editor.swagger.io 进行格式化并预览文本，然后将定义下载为JSON.

The easiest way to get the JSON right is to use http://editor.swagger.io to format and preview the text, and then download the definition as JSON.

在YAML中，请确保缩进正确(多行文本中的所有行都应缩进与键名有关):

In YAML, make sure the indentation is correct (all lines in multiline text need to be indented related to the key name):

# 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

OpenAPI 3.0规范声明工具至少必须支持 CommonMark v.0.27 + ，并且可能在CommonMark顶部支持其他Markdown语法.

OpenAPI 3.0

OpenAPI 3.0 Specification states that tools must support, at a minimum, CommonMark v. 0.27+, and might support additional Markdown syntax on top of CommonMark.

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

CommonMark itself does not have table syntax, but you can use the HTML <table> element as a workaround:

// 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 Editor v.3.6.27 + 支持OAS3的GFM表语法(除了CommonMark)，因此用户这些工具可以使用熟悉的Markdown表语法:

That said, Swagger UI v. 3.22.0+ and Swagger Editor v. 3.6.27+ support GFM table syntax for OAS3 (in addition to CommonMark), so the users of these tools can use the familiar Markdown table syntax:

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

这篇关于如何使用JSON for OpenAPI绘制表格的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！