allOf: combina varios esquemas, por ejemplo para fusionar objetos o extender un esquema base. Funciona como un operadorand.anyOf: acepta datos que coincidan con cualquiera de los esquemas proporcionados. Funciona como un operadoror.oneOf: acepta datos que coincidan exactamente con uno de los esquemas proporcionados. Funciona como un operadorexclusive-or.
oneOf y anyOf de la misma forma y no admite la palabra clave not. Para conocer las especificaciones detalladas de estas palabras clave, consulta oneOf, anyOf, allOf, not en la documentación de OpenAPI.
Cuando combinas dos esquemas de objeto con allOf, Mintlify fusiona las propiedades de ambos en un solo objeto. Esto resulta útil con los componentes reutilizables de OpenAPI.
oneOf o anyOf, las opciones se muestran en un contenedor con pestañas. Especifica un campo title en cada subesquema para nombrar las pestañas. Por ejemplo, así podrías mostrar dos tipos diferentes de direcciones de entrega:
any o undefined se muestran igual que los esquemas oneOf, con un selector que permite a los usuarios elegir una forma concreta antes de enviar una solicitud.
En OpenAPI 3.1, puedes hacer que una propiedad sea obligatoria solo en ciertos casos con las palabras clave if, then, else, dependentRequired y dependentSchemas. Mintlify lee estas palabras clave y etiqueta cada campo afectado en la página del endpoint con una píldora required seguida de su condición.
Por ejemplo, este esquema exige un número de tarjeta para los pagos con tarjeta, un número de cuenta para cualquier otro método de pago y un nombre de empresa siempre que la solicitud incluya un ID fiscal:
card_number: obligatorio simethod=cardaccount_number: obligatorio a menos quemethod=cardcompany_name: obligatorio sitax_idestá definido
const o enum, o si están presentes con required. Si una condición es demasiado compleja para resumirla, el campo muestra en su lugar una píldora conditionally required.
En las especificaciones OpenAPI 3.1 y 3.2, define una carga de archivo como un esquema de tipo string con un contentMediaType binario. El playground de API muestra el campo como un selector de archivos y lo envía como parte de una solicitud multipart/form-data.
application/octet-stream, imágenes, audio, video, PDFs y archivos comprimidos. El playground no trata los tipos de medio estructurados, como application/json, como cargas de archivos.
Usa contentEncoding para describir cómo está codificado el contenido del archivo. Para archivos codificados en base64, configura contentEncoding como base64 o base64url, y el playground tratará el campo como un archivo base64. Para otros valores o sin valor, el playground usa el manejo de archivos binarios. Un valor de contentEncoding sin un contentMediaType binario sigue siendo un campo de texto.
Los valores anteriores format: "binary" y format: "base64" siguen siendo compatibles.
Si tu API devuelve respuestas distintas según los parámetros de entrada, el contexto del usuario u otras condiciones de la solicitud, documenta cada una con la propiedad examples de la respuesta.
Content-Type que devuelve tu API:
- Imágenes (
image/*): se muestran en línea. - Audio (
audio/*): se muestran con un reproductor de audio. - Video (
video/*): se muestran con un reproductor de video. - Todas las demás respuestas: se muestran en un bloque de código.
audio/* y usa la URL de un archivo de audio como valor de ejemplo:
text/event-stream, application/jsonl, application/x-ndjson, application/json-seq y multipart/mixed. Las solicitudes con un cuerpo multipart/form-data no se transmiten en streaming.
Mientras la respuesta se transmite, el panel de respuesta muestra Streaming… y el botón de envío cambia a Stop. Haz clic en Stop para finalizar la solicitud. El playground conserva los datos recibidos y muestra Stream stopped.
El playground muestra el cuerpo transmitido como texto plano, sin formato JSON. Un stream también puede terminar antes:
- El playground deja de leer después de 10 MB y muestra Stream truncated at 10 MB.
- Si la conexión se cierra antes de que termine el stream, el playground muestra Stream interrupted.
- Cuando el proxy del playground está activado, tu API debe enviar los encabezados de respuesta en un plazo de 30 segundos, y el proxy finaliza el stream después de cinco minutos.
webhooks a tu documento OpenAPI junto al campo paths. Para obtener más información sobre cómo definir webhooks, consulta Webhooks en la especificación OpenAPI.
Para crear una página MDX para un webhook, usa webhook en lugar de un método HTTP en el frontmatter openapi:
webhooks de tu especificación OpenAPI.
Los callbacks describen solicitudes fuera de banda que tu API envía a una URL proporcionada por quien la llama, como notificaciones de eventos vinculadas a una operación específica. Cuando una operación define callbacks, la página del endpoint los muestra en una sección contraíble entre las secciones del cuerpo de la solicitud y de la respuesta. Cada callback muestra su método HTTP y su expresión, y usa el mismo diseño de cuerpo y respuesta que la operación principal.
Para obtener más información sobre cómo definir callbacks, consulta Callback object en la especificación OpenAPI.