Zona de pruebas

Permite que los usuarios interactúen con tu API

​

Descripción general

El área de pruebas de la API es un entorno interactivo que permite a los usuarios probar y explorar tus endpoints de API. Los desarrolladores pueden elaborar solicitudes a la API, enviarlas y ver las respuestas sin salir de tu documentación.

El área de pruebas se genera automáticamente a partir de tu especificación de OpenAPI o del esquema de AsyncAPI, por lo que cualquier actualización de tu API se refleja automáticamente en el área de pruebas. También puedes crear manualmente páginas de referencia de la API después de definir una URL base y un método de Autenticación en tu docs.json.

Recomendamos generar tu área de pruebas de la API a partir de una especificación de OpenAPI. Consulta OpenAPI Setup para obtener más información sobre cómo crear tu documento de OpenAPI.

​

Primeros pasos

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

   Asegúrate de que tu archivo de especificación OpenAPI sea válido usando el Swagger Editor o la CLI de Mint.

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

2. Configura `docs.json`.

   Actualiza tu docs.json para hacer referencia a tu especificación OpenAPI. Añade una propiedad openapi a cualquier elemento de navigation para completar automáticamente tu documentación con páginas para cada endpoint especificado en tu documento OpenAPI.

   Este ejemplo genera una página para cada endpoint especificado en openapi.json y las organiza en el grupo “API reference” dentro de tu navigation.

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

   Este ejemplo genera páginas solo para los endpoints GET /users y POST /users. Para generar páginas de otros endpoints, añade endpoints adicionales al arreglo pages.

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

​

Personaliza tu área de pruebas

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

playground · object

Configuración del área de pruebas de la API.

Ocultar playground

display · "interactive" | "simple" | "none"

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.

El valor predeterminado es interactive.

proxy · boolean

Indica si se deben pasar las solicitudes de la API a través de un servidor proxy. De manera predeterminada es true.

examples · object

Configuración de los ejemplos de API generados automáticamente.

Ocultar examples

languages · array of string

Idiomas para los fragmentos de API generados automáticamente.

Los idiomas se muestran en el orden especificado.

defaults · "required" | "all"

Indica si se deben mostrar los parámetros opcionales en los ejemplos de la API. De manera predeterminada es all.

prefill · boolean

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

​

Ejemplo de configuración

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

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. En los fragmentos de código solo se muestran los parámetros obligatorios, y el área de pruebas rellena previamente el cuerpo de la solicitud con valores de ejemplo.

​

Páginas de endpoints personalizadas

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

Ambas opciones te permiten:

• Personalizar los metadatos de la página
• Añadir contenido adicional, como ejemplos
• Controlar el comportamiento del playground por página

Se recomienda la extensión x-mint para que toda tu documentación de API se genere automáticamente a partir de tu especificación de OpenAPI y se mantenga en un solo archivo.

Se recomiendan las páginas MDX individuales para APIs pequeñas o cuando quieras probar cambios por página.

Para más información, consulta Extensión x-mint y Configuración de MDX.

​

Lecturas adicionales

• Configuración de AsyncAPI para obtener más información sobre cómo crear tu esquema de AsyncAPI y generar páginas de referencia de WebSocket.