跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
oneOf, anyOf, allOf 关键字

对于复杂数据类型，OpenAPI 提供了用于组合 schema 的关键字：
  • allOf：将多个 schema 组合在一起（如合并对象或扩展基础 schema），相当于 and 运算符。
  • anyOf：接受与任一提供的 schema 匹配的数据，相当于 or 运算符。
  • oneOf：接受与提供的 schema 中恰好一个匹配的数据，相当于 exclusive-or 运算符。
Mintlify 对 oneOf 和 anyOf 采用相同的处理方式，因为它们在实际使用中很少对 API 产生影响。
有关这些关键字的详细规范，请参阅 OpenAPI 文档。
not 关键字目前不受支持。

​
使用 allOf 组合模式（schema）

当你使用 allOf 时，Mintlify 会对你的 OpenAPI 文档进行预处理，以更易读的方式展示复杂的组合。例如，当你用 allOf 合并两个对象模式（schema）时，Mintlify 会将两者的属性合并到一个对象中。这在利用 OpenAPI 的可复用组件时尤其有用。 
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
​
org_with_users
object

​
使用 oneOf 和 anyOf 提供选项

当你使用 oneOf 或 anyOf 时，这些选项显示在一个带标签页的容器中。在每个子模式中指定一个 title 字段，为你的选项命名。例如，你可以这样展示两种不同类型的收货地址： 
delivery_address:
  oneOf:
    - title: StreetAddress
      type: object
      properties:
        address_line_1:
          type: string
          description: 收件人的街道地址
        # ...
    - title: POBox
      type: object
      properties:
        box_number:
          type: string
          description: 邮政信箱的号码
        # ...
​
delivery_address
object
​
address_line_1
string
住址的街道信息

相关主题

快速入门选项卡发送后续消息