Skip to main content
OpenAPI 3 has some advanced features for describing complex APIs. Here’s how you can use them with Mintlify.

​
oneOf, anyOf, allOf

For complex datatypes, OpenAPI provides the oneOf, anyOf, and allOf keywords, allowing you to combine schemas in certain ways. You can read more about these keywords in the Swagger documentation, but essentially:
  • oneOf functions like an “exclusive-or” operator
  • anyOf functions like an “or” operator
  • allOf functions like an “and” operator
The oneOf and anyOf keywords are treated the same. We have found that, when people use oneOf, they often mean anyOf - and there is often no meaningful difference to the user.
The not keyword is not currently supported.

​
Combining schemas with allOf

Mintlify performs some preprocessing on your OpenAPI document to display these complex combinations in a readable way. For example, when you combine two object schemas with allOf, Mintlify combines the properties of both into a single object. This becomes especially useful when leveraging OpenAPI’s reusable components. 
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

​
Providing options with oneOf and anyOf

When you use oneOf or anyOf, Mintlify displays the options in a tabbed container. To give your options helpful names, make sure to give each subschema a title field. For example, here’s how you might display two different types of delivery addresses: 
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
  • StreetAddress
  • POBox
​
address_line_1
string
The street address of the residence

​
x-codeSamples

If your users interact with your API using an SDK rather than directly through a network request, you can add code samples to your OpenAPI document, and Mintlify will display them in your OpenAPI pages. You can define your code samples using the x-codeSamples extension. This property can be added within any request method, and has the following schema:
​
lang
string
required
The language of the code sample.
​
label
string
The label for the sample. This is useful when providing multiple examples for a single endpoint.
​
source
string
required
The source code of the sample.
Here’s an example of some code samples for a plant tracking app, which has both a Bash CLI 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 });

​
x-hidden and x-excluded

If your pages are autogenerated from an OpenAPI document, but there are some paths that you don’t want to create pages for, you can exclude them from having pages generated by adding the property x-excluded. If you want to have pages generated, but not have them appear in the navigation, add x-hidden. You can add the x-hidden or x-excluded tag under endpoint or webhook paths below the method. Here’s are examples of how that would look in an OpenAPI schema document for an endpoint or a webhook path: 
"paths": {
  "/plants": {
    "get": {
      "description": "Returns all plants from the store",
      "parameters": { ... },
      "responses": { ... }
    }
  },
  "/hidden_plants": {
    "get": {
      "x-hidden": true,
      "description": "Returns all somewhat secret plants from the store",
      "parameters": { ... },
      "responses": { ... }
    }
  },
  "/secret_plants": {
    "get": {
      "x-excluded": true,
      "description": "Returns all top secret plants from the store (do not publish this endpoint!)",
      "parameters": { ... },
      "responses": { ... }
    }
  }
},

"webhooks": {
  "/plants_hook": {
    "post": {
      "description": "Webhook for information about a new plant added to the store",
    }
  },
  "/hidden_plants_hook": {
    "post": {
      "x-hidden": true,
      "description": "Webhook for somewhat secret information about a new plant added to the store"
    }
  },
  "/secret_plants_hook": {
    "post": {
      "x-excluded": true,
      "description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)"
    }
  }
}
⌘I