Advanced Features
Support for advanced OpenAPI features
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” operatoranyOf
functions like an “or” operatorallOf
functions like an “and” operator
oneOf
and anyOf
keywords the same. We have found that, when people use oneOf
, they often mean anyOf
- and there is often no meaningful difference to the user.not
keyword.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
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
...
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:
The language of the code sample.
The label for the sample. This is useful when providing multiple examples for a single endpoint.
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 });
Was this page helpful?