Playground

El playground de API es un entorno interactivo que permite a los usuarios probar y explorar tus endpoints de API. Los desarrolladores pueden crear solicitudes de API, enviarlas y ver las respuestas sin salir de tu documentación. Consulta Trigger an update para ver un ejemplo del playground de API en acción.

Playground de API para el endpoint Trigger an update.

El playground genera páginas interactivas para tus endpoints a partir de tu especificación OpenAPI o esquema AsyncAPI. Si modificas tu API, el playground actualiza automáticamente las páginas correspondientes. Recomendamos generar tu playground de API a partir de una especificación OpenAPI. Sin embargo, puedes crear manualmente páginas de referencia de API después de definir una URL base y un método de autenticación en tu docs.json.

Primeros pasos

Añade tu archivo de especificación de OpenAPI.

Valida tu archivo de especificación de OpenAPI con el Swagger Editor o con el comando de la Mint CLI mint validate.

/your-project
  |- docs.json
  |- openapi.json

Genera páginas de endpoints.

Actualiza tu docs.json para hacer referencia a tu especificación de OpenAPI.Para generar automáticamente páginas para todos los endpoints de tu especificación de OpenAPI, añade una propiedad openapi a cualquier elemento de navegación.Este ejemplo genera una página para cada endpoint definido en openapi.json y organiza las páginas en el grupo “API reference”.

Generate all endpoint pages

"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}

Para generar páginas solo para endpoints específicos, enumera los endpoints en la propiedad pages del elemento de navegación.Este ejemplo genera páginas únicamente para los endpoints GET /users y POST /users. Para generar otras páginas de endpoints, añade más endpoints al arreglo pages.

Generate specific endpoint pages

"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

Personaliza tu área de pruebas de la API

Personaliza tu área de pruebas de la API definiendo las siguientes propiedades en tu docs.json.

object

Configuraciones para el área de pruebas de la API.

Mostrar playground

"interactive" | "simple" | "none" | "auth"

El modo de visualización del área de pruebas de la API.

"interactive": Muestra el área de pruebas interactiva.
"simple": Muestra un endpoint copiable sin área de pruebas.
"none": No muestra nada.
"auth": Muestra el área de pruebas interactiva solo a los usuarios autenticados. Los usuarios no autenticados o los usuarios que no están en los grupos obligatorios no ven ninguna área de pruebas.

El valor predeterminado es interactive.

boolean

Indica si las solicitudes de API deben pasar por el servidor proxy de Mintlify. El valor predeterminado es true.Cuando es true, las solicitudes del playground se enrutan a través de los servidores de Mintlify. Cuando es false, el playground envía las solicitudes directamente desde el navegador a tu API. Establécelo en false cuando tu API acepte solicitudes directas del navegador y no necesites que Mintlify actúe como proxy del tráfico. Por ejemplo, cuando tu API requiere encabezados específicos que no se pueden reenviar a través del proxy o cuando necesitas que la solicitud se origine directamente desde el navegador del usuario por motivos de autenticación.

boolean

Indica si se deben incluir cookies, encabezados de autorización y certificados de cliente TLS en las solicitudes cross-origin cuando proxy es false. El valor predeterminado es false.Cuando es true y proxy es false, el playground envía solicitudes con las credenciales gestionadas por el navegador incluidas. Por ejemplo, cuando tu API utiliza autenticación basada en cookies o tokens de sesión HTTP.Esta opción no tiene efecto cuando proxy es true.

"full"

El modo de visualización de las URL base en los encabezados de los endpoints. Cuando se establece en full, se muestra la URL base completa en cada página del endpoint. De forma predeterminada, solo se muestra la ruta relativa del endpoint.

object

Configuraciones para los ejemplos de API generados automáticamente.

Mostrar examples

array of string

Lenguajes para los fragmentos de API generados automáticamente.Se muestran en el orden especificado.

All supported languages

Nombre visible	Clave	Alias
cURL	`bash`	`curl`, `sh`, `shell`
Python	`python`	`py`
JavaScript	`javascript`	`js`
Node.js	`node`	`nodejs`, `node.js`
PHP	`php`
Go	`go`	`golang`
Java	`java`
Ruby	`ruby`	`rb`
PowerShell	`powershell`
Swift	`swift`
C#	`csharp`	`c#`
.NET	`dotnet`	`.net`, `.NET`, `dot-net`
TypeScript	`typescript`	`ts`
C	`c`
C++	`c++`	`cpp`
Kotlin	`kotlin`	`kt`
Rust	`rust`	`rs`
Dart	`dart`	`flutter`

"required" | "all"

Indica si se muestran los parámetros opcionales en los ejemplos de API. El valor predeterminado es all.

boolean

Indica si se debe rellenar previamente el área de pruebas de la API con datos de ejemplos del esquema. Cuando está habilitado, el área de pruebas completa automáticamente los campos de la solicitud con valores de ejemplo de tu especificación OpenAPI. El valor predeterminado es false.

boolean

Indica si se deben generar ejemplos de código para los endpoints a partir de las especificaciones de API. El valor predeterminado es true. Cuando se establece en false, solo aparecen en el área de pruebas de la API los ejemplos de código redactados manualmente (de x-codeSamples en las especificaciones OpenAPI o de componentes <RequestExample> en MDX).

Configuración de ejemplo

Este ejemplo configura el área de pruebas de la API para que sea interactiva, con fragmentos de código de ejemplo para cURL, Python y JavaScript. Solo muestra los parámetros obligatorios en los fragmentos de código, y el área de pruebas rellena el cuerpo de la solicitud con valores de ejemplo.

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required",
     "prefill": true
   }
 }
}

Visualización del playground basada en la autenticación

Usa el modo de visualización auth para mostrar el playground interactivo solo a usuarios autenticados. Esto es útil cuando quieres que los usuarios puedan consultar públicamente la documentación de tu API mientras restringes el acceso al playground a los usuarios que han iniciado sesión. Cuando display está configurado en auth:

Los usuarios autenticados ven el playground interactivo.
Los usuarios no autenticados no ven ningún playground (equivalente a none).

También puedes combinar auth con la propiedad groups en el frontmatter de la página para restringir el acceso al playground a grupos de usuarios específicos.

Page with group-restricted playground

---
title: "Crear usuario"
openapi: POST /users
playground: auth
groups: ["admin", "developer"]
public: true
---

En este ejemplo:

La página es públicamente visible (cualquiera puede ver la documentación).
Solo los usuarios autenticados que pertenecen a los grupos admin o developer ven el playground interactivo.
Los usuarios que no están en esos grupos no ven ningún playground.

Si la página no tiene la propiedad groups, todos los usuarios autenticados pueden ver el playground interactivo.

El modo de visualización auth requiere que tu documentación tenga la autenticación configurada.

Páginas de endpoints personalizadas

Cuando necesites más control sobre la documentación de tu API, usa la extensión x-mint en tu especificación OpenAPI o crea páginas MDX individuales para tus endpoints. Ambas opciones te permiten:

Personalizar el metadata de la página
Agregar contenido adicional, como ejemplos
Controlar el comportamiento del playground por página

Recomendamos la extensión x-mint para que toda la documentación de tu API se genere automáticamente a partir de tu especificación OpenAPI y se mantenga en un solo archivo. Recomendamos las páginas MDX individuales para APIs pequeñas o cuando quieras experimentar con cambios página por página.

Editar cuerpos de solicitud como JSON

Cuando un endpoint acepta un cuerpo de solicitud JSON (application/json o un tipo de medio +json), la sección del cuerpo del playground muestra un selector Form y JSON. Usa Form para completar un campo a la vez. Usa JSON para editar todo el cuerpo en un editor de código, por ejemplo, para pegar una respuesta de otro endpoint y cambiar algunos valores antes de enviarla.

Form y JSON editan el mismo cuerpo, por lo que los cambios en una vista aparecen en la otra. La solicitud que envías y los ejemplos de código generados siempre coinciden con el cuerpo.
JSON conserva las propiedades que no están en tu esquema OpenAPI y las envía con la solicitud.
Si el JSON no es válido, el playground muestra la línea, la columna y la causa probable del primer error después de que sales de la línea que estás editando. No puedes enviar la solicitud hasta que el JSON sea válido. Si cambias a Form, el playground te pide confirmación antes de reemplazar el JSON no válido por el cuerpo predeterminado.
Pasa el cursor sobre el editor para copiar el JSON o restablecer el cuerpo a su valor predeterminado.
El playground recuerda la vista que elegiste y la usa para otros endpoints.

El selector no aparece para otros tipos de cuerpo de solicitud, como multipart/form-data o application/x-www-form-urlencoded.

Renderizado de respuestas

El playground renderiza automáticamente las respuestas según el encabezado Content-Type devuelto por tu API.

Imágenes: Se renderizan en línea (image/*).
Audio: Se renderiza con un reproductor de audio integrado (audio/*).
Video: Se renderiza con un reproductor de video integrado (video/*). Cualquier respuesta con un tipo de contenido video/*, como video/mp4 o video/webm, se muestra como un video reproducible directamente en el playground.
Todas las demás respuestas: Se muestran en un bloque de código.

Respuestas en streaming

Cuando las respuestas de un endpoint en tu especificación OpenAPI declaran un tipo de medio de streaming, el playground muestra la respuesta a medida que llega en lugar de esperar a que termine la solicitud. Los tipos de medio de streaming son 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 proxy es true, tu API debe enviar los encabezados de respuesta en un plazo de 30 segundos, y el proxy de Mintlify finaliza el stream después de cinco minutos.

Enlaces de anclaje de parámetros

Cada parámetro en el playground de API tiene un enlace de anclaje clicable. Pasa el cursor sobre el nombre de un parámetro para revelar el ícono de enlace y haz clic para copiar una URL directa a ese parámetro. Usa los enlaces de anclaje de parámetros para:

Compartir enlaces a parámetros específicos en conversaciones de soporte o documentación
Navegar directamente a un parámetro desde otra página o recurso externo
Guardar en marcadores los parámetros que consultas con frecuencia

El formato de la URL es tu-url-de-docs/ruta-del-endpoint#nombre-del-parametro. Para parámetros anidados, el anclaje incluye la ruta del elemento padre.

Más información

Configuración de OpenAPI para obtener más información sobre cómo crear tu documento OpenAPI.
Extensión x-mint para obtener más información sobre cómo personalizar las páginas de tus endpoints.
Configuración de MDX para obtener más información sobre cómo crear manualmente páginas individuales de referencia de API.
Configuración de AsyncAPI para obtener más información sobre cómo crear tu esquema AsyncAPI para generar páginas de referencia de WebSocket.

Primeros pasos

Crear contenido

Administra tu sitio

Agente

Assistant

Contenido preparado para agentes

Búsqueda y SEO

Documentar APIs

Integraciones

Referencia

Primeros pasos

Personaliza tu área de pruebas de la API

Configuración de ejemplo

Visualización del playground basada en la autenticación

Páginas de endpoints personalizadas

Editar cuerpos de solicitud como JSON

Renderizado de respuestas

Respuestas en streaming

Enlaces de anclaje de parámetros

Más información

​Primeros pasos

​Personaliza tu área de pruebas de la API

​Configuración de ejemplo

​Visualización del playground basada en la autenticación

​Páginas de endpoints personalizadas

​Editar cuerpos de solicitud como JSON

​Renderizado de respuestas

​Respuestas en streaming

​Enlaces de anclaje de parámetros

​Más información

Primeros pasos

Personaliza tu área de pruebas de la API

Configuración de ejemplo

Visualización del playground basada en la autenticación

Páginas de endpoints personalizadas

Editar cuerpos de solicitud como JSON

Renderizado de respuestas

Respuestas en streaming

Enlaces de anclaje de parámetros

Más información