Saltar al contenido principal

​
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.
Área de pruebas de la API para el endpoint que desencadena 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 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

Agrega tu archivo de especificación de OpenAPI.

Asegúrate de que tu archivo de especificación de 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 de OpenAPI. Agrega la propiedad openapi a cualquier elemento de navigation para autogenerar páginas en tu documentación para cada endpoint definido en tu documento de OpenAPI.Este ejemplo genera una página por cada endpoint definido 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, enuméralos en la propiedad pages del elemento de navigation.Este ejemplo genera páginas únicamente para los endpoints GET /users y POST /users. Para generar páginas de otros endpoints, agrega más endpoints al arreglo pages.
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
Personalización del área de pruebas

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

​
Ejemplo de configuración

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required"
   }
 }
}
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 se muestran los parámetros obligatorios en los fragmentos de código.

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