API Playground
Prueba los endpoints de la API con el playground interactivo. Completa los parámetros, mira ejemplos de código en vivo y envía solicitudes reales.
El playground de API añade un botón interactivo "Try it" a tus páginas de endpoints de API. Los desarrolladores completan los parámetros, ven los ejemplos de código actualizarse en tiempo real y envían solicitudes HTTP reales desde la página de documentación.
Las capturas de pantalla muestran la interfaz en inglés.
Inicio rápido
El playground está activado de forma predeterminada. Cada página con un campo de frontmatter openapi: o api: recibe automáticamente un botón "Try it". CORS se gestiona automáticamente.
No se necesita ninguna configuración de docs.json. Añade un campo openapi: o api: al frontmatter de tu página y el playground aparecerá.
Modos de visualización
El campo display controla lo que el playground puede hacer:
| Modo | Botón "Try it" | Completar parámetros | Código en vivo | Enviar solicitud |
|---|---|---|---|---|
"interactive" (predeterminado) | ✓ | ✓ | ✓ | ✓ |
"simple" | ✓ | ✓ | ✓ | ✗ |
"none" | ✗ | ✗ | ✗ | ✗ |
Experiencia completa del playground. Los desarrolladores completan los parámetros, ven los ejemplos de código actualizarse en vivo y envían solicitudes HTTP reales. Las respuestas se muestran en línea con los códigos de estado, la duración y el cuerpo formateado.
{
"api": {
"playground": {
"display": "interactive"
}
}
}Autenticación
Si tu API requiere autenticación (configurada mediante api.mdx.auth.method en docs.json), el playground muestra un campo de autenticación en la parte superior del formulario de parámetros. Los desarrolladores introducen su clave de API o token directamente en el modal.
Las credenciales se mantienen en memoria solo durante la sesión actual. Nunca se guardan en localStorage ni se conservan entre visitas.
Autocompletado de valores de ejemplo
Cuando tu especificación de OpenAPI incluye valores example en los parámetros y los cuerpos de solicitud, el playground puede completarlos automáticamente:
{
"api": {
"examples": {
"prefill": true
}
}
}Esto ahorra tiempo a los desarrolladores al mostrar valores realistas que pueden modificar en lugar de partir de campos vacíos.
Anulación por página
Anula el modo de visualización global en páginas individuales usando el campo de frontmatter playground:
---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---Útil cuando quieres desactivar el playground globalmente pero activarlo en endpoints de demostración específicos, o viceversa.
| Frontmatter | Comportamiento |
|---|---|
playground: interactive | playground completo en esta página |
playground: simple | playground de solo código en esta página |
playground: none | Sin playground en esta página |
Cómo funciona
El playground se abre como una ventana modal a pantalla completa. Tu página de documentación permanece intacta debajo.
Los parámetros de ruta, consulta, encabezado y cuerpo se muestran como campos de formulario. Los campos obligatorios están marcados. La URL base se obtiene del campo servers de tu especificación de OpenAPI.
A medida que escribes, los ejemplos de código se regeneran en tiempo real en todos los lenguajes configurados. Copia cualquier ejemplo con un clic.
En modo interactivo, haz clic en Send (o presiona Ctrl/Cmd+Enter) para ejecutar la solicitud. La respuesta se muestra debajo con el código de estado, la duración y el cuerpo formateado.
Cuando el playground está abierto, la URL se actualiza para incluir ?playground=open. Comparte esta URL para enlazar a alguien directamente a la vista de playground de un endpoint.
Varios servidores
Cuando la especificación de un endpoint incluye más de una entrada bajo servers — producción y sandbox, por ejemplo — aparece un selector de servidor junto a la URL del endpoint. Lo que el lector elija determina la URL base, el botón de copiar URL, los ejemplos de código en la página y la solicitud que el playground realmente envía, para que nadie copie un curl de producción mientras lee la documentación del sandbox.
Los endpoints con un solo servidor no cambian: sin selector, sin peso adicional en la página.
Atajos de teclado
| Atajo | Acción |
|---|---|
Ctrl/Cmd + Enter | Enviar solicitud |
Escape | Cerrar el playground |
Compatible con ambos tipos de páginas de API
El playground funciona en páginas que usan el formato de frontmatter openapi: o api::
Los parámetros y los esquemas se obtienen automáticamente de tu especificación de OpenAPI. No se necesita configuración adicional.
---
openapi: POST /tickets
---Desarrollo local
Al ejecutar jamdesk dev, los botones "Try it" son visibles, pero el playground en sí es una función exclusiva de producción. Al hacer clic en "Try it" en desarrollo local se muestra una breve notificación en lugar de abrir el modal. Despliega tu documentación para usar el playground completo.
Pruébalo en vivo
Este sitio de documentación tiene el playground activado. Visita la página Ejemplo de OpenAPI y haz clic en "Try it" para verlo en acción con la API de demostración.