在Swagger中描述json参数

Question

问题

根据this和this，Swagger支持复杂的参数，但是当我尝试描述json参数时，Swagger编辑器显示以下问题：

  

无法呈现ParameterRow，请参见控制台。

预期的行为

Json对象作为参数。

YAML

<uses-permission>

要复制...

1. 复制yaml
2. 转到http://editor.swagger.io
3. 粘贴yaml
4. 看到错误

屏幕截图

Answer 1

Swagger编辑器和Swagger UI当前无法使用content渲染OpenAPI 3.0参数，这是一个已知问题：
https://github.com/swagger-api/swagger-ui/issues/4442

This answer提到了一种解决方法，如果您只需要“试用”支持-您可以将参数仅定义为type: string并添加example的JSON数据。您失去了描述查询字符串的JSON模式的能力，但是“尝试一下”将起作用。

      parameters:
        - in: query
          name: filter
          schema:
            type: string                           # <-------
          example: '{"type":"foo","color":"bar"}'  # <-------

注意：如果您正在设计新的API ，而不是描述现有的API，则应在请求正文中张贴复杂数据（例如JSON对象）：

openapi: 3.0.0
...
paths:
  /getLabelUrl.action:
    post:
      requestBody:    # <-----
        content:
          application/json:
            schema:
              type: object
              ...

或者，如果更适合使用查询参数，请考虑将对象“展平”为键=值对，例如：

POST /getLabelUrl.action?type=foo&color=bar

此串行化策略是使用style: form和explode: true定义的。有关查询参数序列化的更多示例，请参见here。

openapi: 3.0.0
...
paths:
  /getLabelUrl.action:
    post:
      parameters:
        - in: query
          name: filter
          schema:
            type: object
            properties:
              type:
                type: string
              color:
                type: string

          # style=form + explode=true is the default serialization strategy
          # so you can omit this
          style: form
          explode: true