OpenAPI：接受任何（复杂）JSON 值的模式

Question

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

我想要一个读取值的路径和一个存储非预定义深度的任何 JSON 值（空值、数字、整数、字符串、对象、数组）的路径。

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

所以我正在尝试通过定义 MixedValue 架构来解决问题：

---
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 属性。

问题： - 有没有办法解决这个问题？ - 这只是 Swagger Editor 错误还是 Swagger 2.0 规范的强大限制？ - 有没有更好的方法（最佳实践）来指定我需要什么？ - 我可以预期 swagger 为某些语言生成的代码有一些限制，符合我的 API 规范吗？

Answer 1

也许这就是您要找的东西"Patterned Objects":

字段模式：^x-

类型：任何

说明：允许扩展 Swagger 架构。字段名称必须以 x- 开头，例如 x-internal-id。该值可以是 null、基本类型、数组或对象。有关详细信息，请参阅供应商扩展。

来源：https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md

Answer 2

可以使用空模式定义任意类型模式 {}:

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

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

或者如果你想要 description:

# 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 值，但某些工具可能仍然支持空值。

在 OpenAPI 3.0 中，type-less 模式允许 null 值，除非其他约束（例如 enum）明确不允许空值。

有关 type-less 架构如何工作的更多详细信息，请参阅。

以下是 Swagger Editor 2.0 如何使用 AnyValue 模式处理正文参数：

虽然我不知道代码生成器如何处理这个问题。

OpenAPI：接受任何（复杂）JSON 值的模式

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

api

json

swagger-2.0

openapi