API Playground
Prueba endpoints de la API directamente desde tu documentación con el playground interactivo. Completa parámetros y envía solicitudes reales.
El API playground agrega un botón interactivo "Try it" a las páginas de endpoint de tu API. Los desarrolladores completan parámetros, ven 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á habilitado de forma predeterminada. Cada página con un campo de frontmatter openapi: o api: obtiene automáticamente un botón "Try it". CORS se gestiona automáticamente.
No se necesita configuración de docs.json. Agrega un campo openapi: o api: al frontmatter de tu página y el playground aparece.
Modos de visualización
El campo display controla qué puede hacer el playground:
| 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 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 códigos de estado, tiempos y cuerpos formateados.
{
"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 entrada de autenticación en la parte superior del formulario de parámetros. Los desarrolladores ingresan su clave de API o token directamente en el modal.
Las credenciales se mantienen solo en memoria durante la sesión actual. Nunca se guardan en localStorage ni se conservan entre visitas.
Pre-completar valores de ejemplo
Cuando tu especificación de OpenAPI incluye valores example en parámetros y cuerpos de solicitud, el playground puede pre-completarlos:
{
"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 el playground deshabilitado globalmente pero habilitado 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 un modal de 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 idiomas 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 código de estado, duración y 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 del playground de un endpoint.
Atajos de teclado
| Atajo | Acción |
|---|---|
Ctrl/Cmd + Enter | Enviar solicitud |
Escape | Cerrar playground |
Funciona con ambos tipos de página de API
El playground funciona en páginas que usan el formato de frontmatter openapi: o api::
Los parámetros y 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. Hacer clic en "Try it" en desarrollo local 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 habilitado. Visita la página Ejemplo de OpenAPI y haz clic en "Try it" para verlo en acción con la API de demostración.