OpenAPI:接受任何(复杂)JSON值的模式 [英] OpenAPI: what schema to accept any (complex) JSON value

问题描述

我正在为其编写Swagger 2.0规范的API基本上是任何JSON值的存储区.

The API for which I'm writing a Swagger 2.0 specification is basically a store for any JSON value.

我想要读取值的路径和存储非预定义深度的任何JSON值(空，数字，整数，字符串，对象，数组)的路径.

I want a path to read value and a path to store any JSON values (null, number, integer, string, object, array) of non-predefined depth.

不幸的是，似乎Swagger 2.0对输入和输出的模式非常严格，并且不允许JSON Schema允许的整个模式集. Swagger编辑器不允许使用混合值(例如，可以是布尔值或整数的属性)或松散定义的数组(必须严格定义项的类型)和对象.

Unfortunately, it seems that Swagger 2.0 is quite strict on schemas for input and output and does not allow the whole set of schemas allowed by JSON Schema. The Swagger editor doesn't allow for example mixed values (for example a property that can be either a boolean or an integer) or loosely defined arrays (the type of items must be strictly defined) and objects.

所以我正在尝试通过定义MixedValue模式进行解决的方法:

So I'm trying a workaround by defining a MixedValue schema:

---
swagger: '2.0'
info:
  version: 0.0.1
  title: Data store API
consumes:
- application/json
produces:
- application/json
paths:
  /attributes/{attrId}/value:
    parameters:
    - name: attrId
      in: path
      type: string
      required: true
    get:
      responses:
        '200':
          description: Successful.
          schema:
            $ref: '#/definitions/MixedValue'
    put:
      parameters:
      - name: value
        in: body
        required: true
        schema:
          $ref: '#/definitions/MixedValue'
      responses:
      responses:
        '201':
          description: Successful.
definitions:
  MixedValue:
    type: object
    properties:
      type:
        type: string
        enum:
        - 'null'
        - boolean
        - number
        - integer
        - string
        - object
        - array
      boolean:
        type: boolean
      number:
        type: number
      integer:
        type: integer
      string:
        type: string
      object:
        description: deep JSON object
        type: object
        additionalProperties: true
      array:
        description: deep JSON array
        type: array
    required:
    - type

但是Swagger编辑器拒绝了宽松定义的object和array属性.

But the Swagger Editor refuses the loosely defined object and array properties.

问题: -有解决此问题的方法吗? -仅仅是Swagger编辑器的错误还是Swagger 2.0规范的强大限制? -是否有更好的方法(最佳实践)来指定我需要的东西? -我可以期望我的API规范对某些语言的挥霍产生的代码会有限制吗?

Questions: - Is there a way to workaround this issue? - Is it just a Swagger Editor bug or a strong limit of the Swagger 2.0 spec? - Is there a better way (best practice) to specify what I need? - Can I expect some limitations in code produced by swagger for some languages with my API spec?

推荐答案

可以这样定义任意类型的模式:

An arbitrary-type schema can be defined like this:

definitions:
  AnyValue: {}

，或者如果您需要description:

definitions:
  AnyValue:
    description: 'Can be anything: string, number, array, object, etc.'

没有定义的type，AnyValue可以是任何东西-字符串，数字，布尔值，数组，对象等.请参见此问题与解答以了解有关type -less模式如何工作的更多详细信息.

Without a defined type, AnyValue can be anything - string, number, boolean, array, object, etc. See this Q&A for more details on how type-less schemas work.

在OpenAPI 3.0中，您可以添加nullable: true以允许null值:

In OpenAPI 3.0 you can add nullable: true to allow the null value:

components:
  schemas:
    AnyValue:
      nullable: true
      description: Can be anything, including null.

以下是 Swagger编辑器2.0 使用AnyValue模式处理正文参数的方式:

Here's how Swagger Editor 2.0 handles a body parameter with the AnyValue schema:

我不知道代码生成器是如何处理的.

I don't know how code generators handle this though.

这篇关于OpenAPI:接受任何(复杂)JSON值的模式的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！