OpenAPI:接受任何(复杂)JSON 值的模式

问题描述

我为其编写 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 模式允许的整个模式集.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 规范可以为某些语言的 swagger 生成的代码带来一些限制吗?

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 using an empty schema {}:

# swagger: '2.0'
definitions:
  AnyValue: {}

# openapi: 3.0.0
components:
  schemas:
    AnyValue: {}

或者如果你想要一个描述:

# swagger: '2.0'
definitions:
  AnyValue:
    description: 'Can be anything: string, number, array, object, etc. (except `null`)'

# openapi: 3.0.0
components:
  schemas:
    AnyValue:
      description: 'Can be anything: string, number, array, object, etc., including `null`'

如果没有定义的type，模式允许任何值.请注意，OpenAPI 2.0 规范不支持 null 值，但某些工具可能仍然支持 null.

Without a defined type, a schema allows any values. Note that OpenAPI 2.0 Specification does not support null values, but some tools might support nulls nevertheless.

在 OpenAPI 3.0 中，type-less 模式允许 null 值，除非其他约束(例如 enum)明确禁止使用 null.

In OpenAPI 3.0, type-less schemas allow null values unless nulls are explicitly disallowed by other constraints (such as an enum).

请参阅此问答，详细了解无type 架构的工作原理.

See this Q&A for more details on how type-less schemas work.

以下是 Swagger Editor 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 值的模式的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！