​
Descripción general

El área de pruebas 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.
Área de pruebas de API para el endpoint que activa una actualizació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 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 API a partir de una especificación de OpenAPI. Consulta Configuración de OpenAPI para obtener más información sobre cómo crear tu documento de OpenAPI.

​
Primeros pasos

1

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

Verifica que tu archivo de especificación de OpenAPI sea válido usando el Swagger Editor o la Mint CLI.
/your-project
  |- docs.json
  |- openapi.json
2

Configura `docs.json`.

Actualiza tu docs.json para referenciar tu especificación de OpenAPI. Agrega la propiedad openapi a cualquier elemento de navegación para completar automáticamente tu documentación con páginas para cada endpoint definido en tu documento de OpenAPI.Este ejemplo genera una página para cada endpoint definido en openapi.json y las organiza bajo el grupo “API reference” en la navegación.
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
Para generar páginas solo de endpoints específicos, enuméralos en la propiedad pages del elemento de navegación.Este ejemplo genera páginas solo para los endpoints GET /users y POST /users. Para generar páginas de otros endpoints, añade más endpoints al arreglo pages.
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
Personalizar tu área de pruebas

Puedes personalizar tu área de pruebas de API definiendo las siguientes propiedades en tu docs.json.
​
playground
object
Configuración del área de pruebas de API.
​
examples
object
Configuración de los ejemplos de API generados automáticamente.

​
Configuración de ejemplo

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required"
   }
 }
}
Este ejemplo configura el Área de pruebas de API como 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.

​
Páginas de endpoints personalizadas

Cuando necesites mayor 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 área de pruebas por página
Se recomienda usar 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 único archivo. Se recomiendan las páginas MDX individuales para APIs pequeñas o cuando quieras experimentar con cambios por página. Para obtener más información, consulta Extensión x-mint y Configuración de MDX.

​
Lecturas recomendadas

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