Advanced Features

Support for advanced OpenAPI features

OpenAPI 3 offers advanced features for complex APIs. Here’s how to use them with Mintlify.

oneOf, anyOf, allOf

OpenAPI provides keywords to combine schemas:

• oneOf - exclusive-or operator
• anyOf - or operator
• allOf - and operator

Mintlify treats oneOf and anyOf the same way.

The not keyword is not currently supported.

Using allOf

Mintlify combines properties of object schemas using allOf. Example:

org_with_users:
  allOf:
    - $ref: '#/components/schemas/Org'
    - type: object
      properties:
        users:
          type: array
          description: Array of organization users

Using oneOf and anyOf

Options are displayed in tabs. Use title field for clear labels:

delivery_address:
  oneOf:
    - title: StreetAddress
      type: object
      properties:
        address_line_1:
          type: string
    - title: POBox
      type: object
      properties:
        box_number:
          type: string

x-codeSamples

Add SDK examples to your API documentation using x-codeSamples. Required fields:

lang

string

required

Code language

label

string

Sample label

source

string

required

Sample code

Example:

paths:
  /plants:
    get:
      x-codeSamples:
        - lang: bash
          source: |
            planter list -u
        - lang: javascript
          source: |
            const planter = require('planter');
            planter.list({ unwatered: true });