Combine schemas
OpenAPI provides keywords for combining schemas:allOf: Combines multiple schemas, like merging objects or extending a base schema. Functions like anandoperator.anyOf: Accepts data matching any of the provided schemas. Functions like anoroperator.oneOf: Accepts data matching exactly one of the provided schemas. Functions like anexclusive-oroperator.
oneOf and anyOf identically, and doesn’t support the not keyword. For detailed specifications of these keywords, see oneOf, anyOf, allOf, not in the OpenAPI documentation.
Merge objects with allOf
When you combine two object schemas with allOf, Mintlify merges the properties of both into a single object. This is useful with OpenAPI’s reusable components.
Offer options with oneOf and anyOf
When you use oneOf or anyOf, the options display in a tabbed container. Specify a title field in each subschema to name the tabs. For example, here’s how you might display two different types of delivery addresses:
any or undefined render the same way as oneOf schemas, with a picker that lets users select a concrete shape before sending a request.
Conditional requirements
In OpenAPI 3.1, you can make a property required only in certain cases with theif, then, else, dependentRequired, and dependentSchemas keywords. Mintlify reads these keywords and labels each affected field on the endpoint page with a required pill followed by its condition.
For example, this schema requires a card number for card payments, an account number for every other payment method, and a company name whenever the request includes a tax ID:
card_number: required ifmethod=cardaccount_number: required unlessmethod=cardcompany_name: required iftax_idis set
const or enum, or for presence with required. If a condition is too complex to summarize, the field shows a conditionally required pill instead.
File uploads
For OpenAPI 3.1 and 3.2 specifications, define a file upload as a string schema with a binarycontentMediaType. The API playground shows the field as a file input and sends it as part of a multipart/form-data request.
application/octet-stream, images, audio, video, PDFs, and archives. The playground doesn’t treat structured media types such as application/json as file uploads.
Use contentEncoding to describe how the file content is encoded. For base64-encoded files, set contentEncoding to base64 or base64url, and the playground treats the field as a base64 file. For other values or no value, the playground uses binary file handling. A contentEncoding value without a binary contentMediaType remains a text field.
The older format: "binary" and format: "base64" values remain supported.
Multiple response examples
If your API returns different responses based on input parameters, user context, or other conditions of the request, document each one with theexamples property on the response.
Response content types
The playground renders responses based on theContent-Type header that your API returns:
- Images (
image/*): Rendered inline. - Audio (
audio/*): Rendered with an audio player. - Video (
video/*): Rendered with a video player. - All other responses: Displayed in a code block.
audio/* and use the URL of an audio file as the example value:
Streaming responses
If an endpoint’s responses declare a streaming media type, the playground shows the response as it arrives instead of waiting for the request to finish. Streaming media types aretext/event-stream, application/jsonl, application/x-ndjson, application/json-seq, and multipart/mixed. Requests with a multipart/form-data body don’t stream.
While the response streams, the response panel shows Streaming… and the send button changes to Stop. Click Stop to end the request. The playground keeps the data it received and shows Stream stopped.
The playground displays a streamed body as plain text, without JSON formatting. A stream can also end early:
- The playground stops reading after 10 MB and shows Stream truncated at 10 MB.
- If the connection closes before the stream finishes, the playground shows Stream interrupted.
- When the playground proxy is on, your API must send response headers within 30 seconds, and the proxy ends the stream after five minutes.
Webhooks
Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. OpenAPI 3.1 and later documents support webhooks. Add awebhooks field to your OpenAPI document alongside the paths field. For more information on defining webhooks, see Webhooks in the OpenAPI specification.
To create an MDX page for a webhook, use webhook instead of an HTTP method in the openapi frontmatter:
webhooks field.
Callbacks
Callbacks describe out-of-band requests that your API sends to a URL provided by the caller, such as event notifications tied to a specific operation. When an operation definescallbacks, the endpoint page shows them in a collapsible section between the request body and response sections. Each callback shows its HTTP method and expression, and uses the same body and response layout as the parent operation.
For more information on defining callbacks, see Callback object in the OpenAPI specification.