playground de API
Prueba los endpoints de la API directamente desde tu documentación con el playground interactivo. Rellena parámetros, consulta ejemplos de código en vivo y envía solicitudes reales.
El API playground añade un botón interactivo "Try it" a tus páginas de endpoints de la API. Los desarrolladores pueden rellenar parámetros, ver cómo los ejemplos de código se actualizan en tiempo real y enviar solicitudes HTTP reales, todo sin salir de tu documentación.
Las capturas de pantalla muestran la interfaz en inglés.
Las capturas de pantalla muestran la interfaz en inglés; la funcionalidad es idéntica en todos los idiomas.
Inicio rápido
El playground está habilitado por defecto. Cada página con un campo frontmatter openapi: o api: obtiene automáticamente un botón "Try it". CORS se gestiona automáticamente.
No se necesita ninguna configuración en docs.json. Añade un campo openapi: o api: al frontmatter de tu página y el playground aparece.
Modos de visualización
El campo display controla lo que el playground puede hacer:
| Modo | Botón "Try it" | Rellenar parámetros | Código en vivo | Enviar solicitud |
|---|---|---|---|---|
"interactive" (predeterminado) | ✓ | ✓ | ✓ | ✓ |
"simple" | ✓ | ✓ | ✓ | ✗ |
"none" | ✗ | ✗ | ✗ | ✗ |
Experiencia completa de playground. Los desarrolladores rellenan 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 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.
Pre-rellenar valores de ejemplo
Cuando tu especificación OpenAPI incluye valores example en parámetros y cuerpos de solicitud, el playground puede pre-rellenarlos:
{
"api": {
"examples": {
"prefill": true
}
}
}Esto ahorra tiempo a los desarrolladores mostrando valores realistas que pueden modificar, en lugar de empezar con campos vacíos.
Anulación por página
Anula el modo de visualización global en páginas individuales usando el campo 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 solo de código en esta página |
playground: none | Sin playground en esta página |
Cómo funciona
El playground se abre como una superposición modal a pantalla completa. Tu página de documentación permanece intacta debajo.
Los parámetros de ruta, consulta, cabecera 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 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 Enviar (o pulsa Ctrl/Cmd+Enter) para ejecutar la solicitud. La respuesta se muestra a continuación 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 del playground de un endpoint.
Atajos de teclado
| Atajo | Acción |
|---|---|
Ctrl/Cmd + Enter | Enviar solicitud |
Escape | Cerrar playground |
Compatible con ambos tipos de páginas API
El playground funciona en páginas que usan el formato frontmatter openapi: o api::
Los parámetros y esquemas se obtienen automáticamente de tu especificación 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 solo 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 habilitado. Visita la página OpenAPI Example y haz clic en "Try it" para verlo en acción con la API de demostración.