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.

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.

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

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

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

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

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
   }
 }
}

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.

---
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.

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.

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.

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.

• 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.