OpenAPI 3 offers several advanced ways to describe complex APIs. Let’s explore how to use these features with Mintlify.

​
oneOf, anyOf, allOf

OpenAPI provides three special keywords to help you work with complex data types: oneOf, anyOf, and allOf. These keywords let you combine different data structures. Here’s what each one does:

  • oneOf: Means “pick exactly one option from the list”
  • anyOf: Means “pick one or more options from the list”
  • allOf: Means “include everything from all options”
In Mintlify, we handle oneOf and anyOf the same way. We’ve found that most developers use these terms interchangeably, and the difference rarely matters to users.
Note: Mintlify doesn’t support the not keyword at this time.

​
Using allOf to Combine Data Structures

Mintlify makes it easy to read combined data structures. For example, when you join two objects with allOf, we show all their properties together in one place. This is especially helpful when you’re using reusable components in OpenAPI.

org_with_users:
  allOf:
    - $ref: '#/components/schemas/Org'
    - type: object
      properties:
        users:
          type: array
          description: An array containing all users in the organization
...
components:
  schemas:
    Org:
      type: object
      properties:
        id:
          type: string
          description: The ID of the organization
​
org_with_users
object

​
Offering Choices with oneOf and anyOf

When you use oneOf or anyOf, Mintlify shows the options in tabs. To make these tabs easy to understand, give each option a clear title. Here’s an example showing two different ways to write a delivery address:

delivery_address:
  oneOf:
    - title: StreetAddress
      type: object
      properties:
        address_line_1:
          type: string
          description: The street address of the recipient
        ...
    - title: POBox
      type: object
      properties:
        box_number:
          type: string
          description: The number of the PO Box
        ...
​
delivery_address
object
​
address_line_1
string

The street address of the residence

​
x-codeSamples

If your users work with your API through an SDK instead of direct API calls, you can add example code to your documentation. Use the x-codeSamples feature to add these examples. You can add this to any API endpoint, and it needs:

​
lang
string
required

The programming language used in the example

​
label
string

A name for the example (helpful when you have multiple examples)

​
source
string
required

The actual code for the example

Here’s an example from a plant tracking app that has both a command-line tool and a JavaScript SDK:

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