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

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.
​
examples
object
Configuración de los ejemplos de API generados automáticamente.

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