OpenAPI: what schema to accept any (complex) JSON value

问题

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

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.

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.

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

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

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?

回答1:

An arbitrary-type schema can be defined like this:

definitions:
  AnyValue: {}

or if you want a description:

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

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.

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.

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.

回答2:

Maybe this is what your are looking for "Patterned Objects":

Field Pattern: ^x-

Type: Any

Description: Allows extensions to the Swagger Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Source: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md

来源：https://stackoverflow.com/questions/32841298/openapi-what-schema-to-accept-any-complex-json-value

标签

json

api

swagger-2.0

openapi