Saltar al contenido principal

​
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 OpenAPI o del esquema AsyncAPI, por lo que cualquier actualización de tu API se refleja automáticamente allí. 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 OpenAPI. Consulta Configuración de OpenAPI para obtener más información sobre cómo crear tu documento de OpenAPI.

​
Primeros pasos

1

Add your OpenAPI specification file.

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

Configure `docs.json`.

Actualiza tu docs.json para hacer referencia a tu especificación de OpenAPI. Agrega una propiedad openapi a cualquier elemento de navegación para rellenar automáticamente tu documentación con páginas para cada endpoint especificado en tu documento de OpenAPI.Este ejemplo genera una página para cada endpoint especificado en openapi.json y las organiza en el grupo “API reference” de tu navegación.
"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 navegación.Este ejemplo genera páginas solo para los endpoints GET /users y POST /users. Para generar otras páginas de endpoints, agrega endpoints adicionales 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.

​
Ejemplo de configuración

{
 "api": {
   "playground": {
     "display": "interactivo"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "obligatorio"
   }
 }
}
Este ejemplo configura el área de pruebas de API para que sea interactiva e incluya 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 personalizadas de endpoints

Cuando necesites más control sobre la documentación de tu 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
  • Agregar 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 experimentar con cambios por página. Para obtener 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.