API Playground

Herramientas de IA

Reduzca el tiempo de desarrollo y permita que sus lectores prueben sus API directamente desde la referencia de la API con un API playground.


Con Try It Out, todos los encabezados, parámetros de consulta, datos de formulario y campos del cuerpo de la solicitud se rellenan previamente con los ejemplos que usted proporciona en la especificación OpenAPI. Los lectores pueden modificar los campos y realizar una solicitud a la API directamente desde la referencia de la API. Los encabezados y los parámetros se validan según su tipo, y se muestran los enums si están disponibles. Los usuarios pueden iniciar flujos de OAuth 2.0 directamente desde la referencia de la API para obtener tokens de acceso.

Se mostrará la respuesta de la solicitud a la API, junto con el código de estado. Los lectores pueden pasar el cursor sobre el código de estado para ver los encabezados de la respuesta.

Requisitos previos para habilitar Try It Out

Antes de habilitar Try It Out, debe realizar dos configuraciones externas:

  1. Configure los encabezados CORS para el dominio de su documentación. Todas las solicitudes se realizan directamente desde el navegador, por lo que debe configurar los encabezados CORS para permitir que el dominio de la documentación haga solicitudes a su API. Los encabezados CORS deben permitir que el origen del sitio de documentación realice cualquier solicitud HTTP, con todos los encabezados que pueda esperar enviar, y exponer todos los encabezados devueltos. La respuesta de los encabezados CORS debería verse así:

Access-Control-Allow-Origin: your.docs.com # change to your docs site origin Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, PATCH Access-Control-Allow-Headers: Authorization, Content-Type, Accept Access-Control-Expose-Headers: * Access-Control-Max-Age: 86400

  1. (Opcional) Configure su cliente OAuth2 para redirigir a nuestra URL de redirección. Si su API usa OAuth2 y desea que el lector pueda generar un token directamente desde el API playground, debe añadir nuestra URL de redirección a su cliente OAuth2. Consulte Autenticación OAuth 2.0.

Habilitar Try It Out

Para habilitar Try It Out en una referencia de API, marque Show Try It Out en la configuración de la referencia de la API .

Compatibilidad con Try It Out

Try It Out es compatible con todas las operaciones de la API excepto:

  • Respuestas que no tengan un tipo de medio JSON o de texto plano.

  • Solicitudes que suben archivos.

Todas las solicitudes se realizan directamente desde el navegador, por lo que debe asegurarse de que la API devuelva los encabezados CORS correctos para el dominio de su documentación.

Personalizar los valores de autenticación

Para personalizar los valores de autenticación, por ejemplo en el encabezado y en la cadena de consulta, contáctenos.

Autenticación OAuth 2.0

Para permitir la autenticación OAuth 2.0 dentro del API playground, debe añadir la siguiente URL de redirección a la configuración de su cliente Auth2.0:

https://<docs-site>/$reader-oauth2

Por ejemplo:

https://docs.developerhub.io/$reader-oauth2.

Una vez configurado, puede habilitar la autenticación OAuth 2.0 marcando Show OAuth2 Authentication en la configuración de la referencia de la API .


URL de redirección

Si también desea permitir la autenticación OAuth 2.0 en el editor, debe añadir la siguiente URL de redirección: https://app.developerhub.io/$reader-oauth2. Sin embargo, esta no debe usarse en una API de producción.

Interceptores personalizados

Los interceptores personalizados le permiten modificar una solicitud antes de enviarla. Esto puede ser útil si, por ejemplo, necesita añadir firmas digitales. Los interceptores personalizados son middleware escrito en javascript.

¿Cómo configurar interceptores personalizados?

Para configurar interceptores personalizados:

  1. Edite las Etiquetas HEAD personalizadas.

  2. Añada un script que registre cada interceptor personalizado necesario mediante la función window.registerCustomInterceptor.

Función: registerCustomInterceptor.

Devuelve: nada.

Argumentos: Function - function(data, next). Donde data tiene la siguiente definición:

{ api: { // Read-Only id: number, slug: string }, verb: string, // API verb (GET, POST, DELETE, PUT or PATCH) - Read-Only url: string, // Example: https://api.example.com/pet/dog body: string, // Most probably the JSON request body, stringified. headers: {[key: string]: string}, // Header key-value params: {[key: string]: string} // Form data or query string key-value }

Y next es una función que debe llamarse una vez por cada interceptor personalizado, proporcionando como argumento los datos modificados, para pasarlos al siguiente interceptor personalizado.

Ejemplos de interceptores personalizados

  1. No tiene ningún efecto. Solo registra los datos:

window.registerCustomInterceptor(function (data, next) { console.log('Custom Interceptor', data); next(data); });

  1. Añade un nuevo encabezado:

window.registerCustomInterceptor(function (data, next) { data.headers['x-header'] = 'y-value'; next(data); });

  1. Modifica los datos del formulario:

window.registerCustomInterceptor(function (data, next) { if (data.params['x-param']) { data.params['x-param'] = 'y-param'; } next(data); });

  1. Modifica el cuerpo JSON solo en una referencia de API determinada:

window.registerCustomInterceptor(function (data, next) { if (data.api.slug !== 'test-api') { return next(data); } var body = JSON.parse(data.body); body['name'] = 'Apu the monkey'; data.body = JSON.stringify(body); next(data); });

Solución de problemas

La solicitud falla

Si la solicitud falla con el mensaje "Request failed (Unknown Error)" y estado 0, asegúrese de que los encabezados CORS estén configurados correctamente. Puede confirmar que este es el problema revisando las DevTools de su navegador. Un error así se mostraría en las DevTools de Chrome: Access to XMLHttpRequest at '<url>' from origin '<url>' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Sin encabezados de respuesta

Si no se envían los encabezados de respuesta, asegúrese de que su API devuelva el encabezado Access-Control-Expose-Headers: *, que permite al navegador leer los encabezados de la respuesta.

  Última actualización por Zaid Daba'een el Mar 31, 2025
Creado con DeveloperHub

Need help? Visit our community forums or contact us.

Editar en GitHub
Tabla de Contenido
API PlaygroundRequisitos previos para habilitar Try It OutHabilitar Try It OutCompatibilidad con Try It OutPersonalizar los valores de autenticaciónAutenticación OAuth 2.0Interceptores personalizadosSolución de problemas¿Cómo configurar interceptores personalizados?Ejemplos de interceptores personalizadosLa solicitud fallaSin encabezados de respuesta