在Swagger中描述json参数

Question

问题

根据这个和这个扬鞭支持复杂的参数，但是当我试图描述一个JSON参数扬鞭编辑器显示了以下问题：

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

预期行为

Json对象作为参数。

YAML

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Trackmeeasy API
paths:
  /getLabelUrl.action:
    post:
      parameters:
        - in: query
          name: filter
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  color:
                    type: string
      responses:
        '200':
          description: OK

复制...

1. 复制yaml
2. 前往http://editor.swagger.io
3. 糊状Yaml
4. 看到错误

屏幕截图

Answer 1

Swagger UI 3.23.8+和Swagger Editor 3.6.34+content支持OpenAPI 3.0参数。

如果您使用的是早期版本的UI或编辑器，则可以使用此替代方法来获得“试用”支持-即将参数定义为just type: string并添加exampleJSON数据。您失去了描述查询字符串的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。有关查询参数序列化的更多示例，请参见此处。

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