OpenAPI 规范 v3.1.0

Schema 对象允许定义输入和输出数据类型。这些类型可以是对象，也可以是基本类型和数组。此对象是JSON Schema 规范草案 2020-12的超集。

有关属性的更多信息，请参阅JSON Schema 核心和JSON Schema 验证。

除非另有说明，否则属性定义遵循 JSON Schema 的定义，并且不添加任何其他语义。在 JSON Schema 指出行为由应用程序定义（例如，对于注释）的地方，OAS 也将语义定义推迟到使用 OpenAPI 文档的应用程序。

4.8.24.1 属性

OpenAPI Schema 对象方言被定义为除了 JSON Schema 草案 2020-12 中指定的词汇表之外，还需要OAS 基本词汇表。通用元模式。此规范版本的 OpenAPI Schema 对象方言由 URI https://spec.openapis.org.cn/oas/3.1/dialect/base（“OAS 方言模式 ID”）标识。以下属性取自 JSON Schema 规范，但其定义已由 OAS 扩展

description - [CommonMark] 语法可以用于富文本表示。
format - 有关更多详细信息，请参阅数据类型格式。虽然依赖于 JSON Schema 定义的格式，但 OAS 提供了一些其他预定义格式。

除了构成 OAS 方言的 JSON Schema 属性外，Schema 对象还支持来自任何其他词汇表的关键字或完全任意的属性。OpenAPI 规范的基本词汇表包含以下关键字

4.8.24.2 固定字段

字段名称	类型	描述
discriminator	Discriminator 对象	添加对多态性的支持。鉴别器是一个对象名称，用于区分可能满足有效负载描述的其他模式。有关更多详细信息，请参阅组合和继承。
xml	XML 对象	此对象可以仅用于属性模式。它对根模式没有影响。添加其他元数据以描述此属性的 XML 表示形式。
externalDocs	外部文档对象	此模式的其他外部文档。
example	任何	一个自由格式的属性，用于包含此模式实例的示例。为了表示 JSON 或 YAML 中无法自然表示的示例，可以使用字符串值来包含示例，并在必要时进行转义。已弃用： `example` 属性已弃用，取而代之的是 JSON Schema `examples` 关键字。不鼓励使用 `example`，并且此规范的更高版本可能会将其删除。

此对象可以扩展规范扩展，但如前所述，其他属性可以省略此对象中的 x- 前缀。

4.8.24.2.1 组合和继承（多态）

OpenAPI 规范允许使用 JSON Schema 的 allOf 属性组合和扩展模型定义，实际上提供了模型组合。allOf 获取一个对象定义数组，这些定义独立验证，但共同组成一个对象。

虽然组合提供了模型的可扩展性，但它并不意味着模型之间存在层次结构。为了支持多态性，OpenAPI 规范添加了 discriminator 字段。使用时，discriminator 将是用于确定哪个模式定义验证模型结构的属性的名称。因此，discriminator 字段必须是必需字段。有两种方法可以为继承的实例定义鉴别器的值。

使用模式名称。
通过使用新值覆盖属性来覆盖模式名称。如果存在新值，则优先于模式名称。因此，没有给定 ID 的内联模式不能用于多态性。

4.8.24.2.2 XML 建模

xml 属性允许在将 JSON 定义转换为 XML 时进行额外的定义。XML 对象包含有关可用选项的其他信息。

4.8.24.2.3 指定 Schema 方言

对于工具来说，能够确定任何给定资源希望使用哪种方言或元模式非常重要：JSON Schema 核心、JSON Schema 验证、OpenAPI Schema 方言或某些自定义元模式。

$schema 关键字可以出现在任何根 Schema 对象中，如果存在，则必须用于确定处理模式时应使用哪种方言。这允许使用符合 JSON Schema 其他草案（而不是默认的草案 2020-12 支持）的 Schema 对象。工具必须支持OAS 方言模式 ID，并且可以支持 $schema 的其他值。

为了允许对 OAS 文档中包含的所有 Schema 对象使用不同的默认 $schema 值，可以在OpenAPI 对象中设置 jsonSchemaDialect 值。如果未设置此默认值，则必须对这些 Schema 对象使用 OAS 方言模式 ID。Schema 对象中的 $schema 值始终会覆盖任何默认值。

当从不是 OAS 文档的外部资源（例如，裸 JSON Schema 资源）引用 Schema 对象时，该资源中模式的 $schema 关键字的值必须遵循JSON Schema 规则。

4.8.24.3 Schema 对象示例

4.8.24.3.1 原始示例

{
  "type": "string",
  "format": "email"
}

type: string
format: email

4.8.24.3.2 简单模型

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/Address"
    },
    "age": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
    }
  }
}

type: object
required:
- name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0

4.8.24.3.3 具有 Map/Dictionary 属性的模型

对于简单的字符串到字符串映射

{
  "type": "object",
  "additionalProperties": {
    "type": "string"
  }
}

type: object
additionalProperties:
  type: string

对于字符串到模型的映射

{
  "type": "object",
  "additionalProperties": {
    "$ref": "#/components/schemas/ComplexModel"
  }
}

type: object
additionalProperties:
  $ref: '#/components/schemas/ComplexModel'

4.8.24.3.4 具有示例的模型

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "example": {
    "name": "Puma",
    "id": 1
  }
}

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
- name
example:
  name: Puma
  id: 1

4.8.24.3.5 具有组合的模型

{
  "components": {
    "schemas": {
      "ErrorModel": {
        "type": "object",
        "required": [
          "message",
          "code"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "code": {
            "type": "integer",
            "minimum": 100,
            "maximum": 600
          }
        }
      },
      "ExtendedErrorModel": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorModel"
          },
          {
            "type": "object",
            "required": [
              "rootCause"
            ],
            "properties": {
              "rootCause": {
                "type": "string"
              }
            }
          }
        ]
      }
    }
  }
}

components:
  schemas:
    ErrorModel:
      type: object
      required:
      - message
      - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf:
      - $ref: '#/components/schemas/ErrorModel'
      - type: object
        required:
        - rootCause
        properties:
          rootCause:
            type: string

4.8.24.3.6 具有多态支持的模型

{
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "discriminator": {
          "propertyName": "petType"
        },
        "properties": {
          "name": {
            "type": "string"
          },
          "petType": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "petType"
        ]
      },
      "Cat": {
        "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "huntingSkill": {
                "type": "string",
                "description": "The measured skill for hunting",
                "default": "lazy",
                "enum": [
                  "clueless",
                  "lazy",
                  "adventurous",
                  "aggressive"
                ]
              }
            },
            "required": [
              "huntingSkill"
            ]
          }
        ]
      },
      "Dog": {
        "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "packSize": {
                "type": "integer",
                "format": "int32",
                "description": "the size of the pack the dog is from",
                "default": 0,
                "minimum": 0
              }
            },
            "required": [
              "packSize"
            ]
          }
        ]
      }
    }
  }
}

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
      - name
      - petType
    Cat:  ## "Cat" will be used as the discriminator value
      description: A representation of a cat
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        properties:
          huntingSkill:
            type: string
            description: The measured skill for hunting
            enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
        required:
        - huntingSkill
    Dog:  ## "Dog" will be used as the discriminator value
      description: A representation of a dog
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        properties:
          packSize:
            type: integer
            format: int32
            description: the size of the pack the dog is from
            default: 0
            minimum: 0
        required:
        - packSize