> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 复杂数据类型

> 使用 oneOf、anyOf 和 allOf 关键字描述具有灵活 schema 的 API，支持可选属性、多态性和多种数据格式。

当你的 API 接受多种数据格式、包含条件字段或采用继承模式时，OpenAPI 的 schema 组合关键字可帮助你为这些灵活的结构编写文档。通过 `oneOf`、`anyOf` 和 `allOf`，你可以描述既能处理不同输入类型、又能将多个 schema 组合成完整数据模型的 API。

<div id="oneof-anyof-allof-keywords">
  ## `oneOf`, `anyOf`, `allOf` 关键字
</div>

对于复杂数据类型，OpenAPI 提供了用于组合 schema 的关键字：

* `allOf`：将多个 schema 组合在一起（如合并对象或扩展基础 schema），相当于 `and` 运算符。
* `anyOf`：接受与任一提供的 schema 匹配的数据，相当于 `or` 运算符。
* `oneOf`：接受与提供的 schema 中恰好一个匹配的数据，相当于 `exclusive-or` 运算符。

<Warning>Mintlify 对 `oneOf` 和 `anyOf` 采用相同的处理方式，因为它们在实际使用中很少对 API 产生影响。</Warning>

有关这些关键字的详细规范，请参阅 [OpenAPI 文档](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/)。

<Info>`not` 关键字目前不受支持。</Info>

<div id="combining-schemas-with-allof">
  ### 使用 `allOf` 组合模式（schema）
</div>

当你使用 `allOf` 时，Mintlify 会对你的 OpenAPI 文档进行预处理，以更易读的方式展示复杂的组合。例如，当你用 `allOf` 合并两个对象模式（schema）时，Mintlify 会将两者的属性合并到一个对象中。这在利用 OpenAPI 的可复用[组件](https://swagger.io/docs/specification/components/)时尤其有用。

```yaml theme={null}
org_with_users:
  allOf:
    - $ref: '#/components/schemas/Org'
    - type: object
      properties:
        users:
          type: array
          description: 包含组织中所有用户的数组
# ...
components:
  schemas:
    Org:
      type: object
      properties:
        id:
          type: string
          description: 组织的 ID
```

<ParamField body="org_with_users" type="object">
  <Expandable>
    <ParamField body="id" type="string">
      组织的 ID
    </ParamField>

    <ParamField body="users" type="object[]">
      包含该组织所有用户的数组
    </ParamField>
  </Expandable>
</ParamField>

<div id="any-and-undefined-types">
  ### `any` 和 `undefined` 类型
</div>

类型为 `any` 或 `undefined` 的字段渲染方式与 `oneOf` 模式相同，会提供一个选择器，让用户在发送请求前选择一个具体的形态。这样即使模式没有将值限定为单一类型，API playground 仍能呈现有意义的输入。

<div id="providing-options-with-oneof-and-anyof">
  ### 使用 `oneOf` 和 `anyOf` 提供选项
</div>

当你使用 `oneOf` 或 `anyOf` 时，这些选项显示在一个带标签页的容器中。在每个子模式中指定一个 `title` 字段，为你的选项命名。例如，你可以这样展示两种不同类型的收货地址：

```yaml theme={null}
delivery_address:
  oneOf:
    - title: StreetAddress
      type: object
      properties:
        address_line_1:
          type: string
          description: 收件人的街道地址
        # ...
    - title: POBox
      type: object
      properties:
        box_number:
          type: string
          description: 邮政信箱的号码
        # ...
```

<ParamField body="delivery_address" type="object">
  <div className="mt-4 rounded-xl border border-gray-100 px-4 pb-4 pt-2 dark:border-white/10">
    <Tabs>
      <Tab title="StreetAddress">
        <ParamField body="address_line_1" type="string">
          住址的街道信息
        </ParamField>
      </Tab>

      <Tab title="POBox">
        <ParamField body="box_number" type="string">
          邮政信箱号码
        </ParamField>
      </Tab>
    </Tabs>
  </div>
</ParamField>