Try It! es la consola interactiva de API de Document360, integrada directamente en tu referencia de API publicada. Permite a los desarrolladores enviar peticiones reales a los endpoints de la API y ver respuestas en tiempo real sin dejar la documentación ni escribir código.
Este artículo explica cómo funciona Pruébalo!, qué necesitan los desarrolladores para usarlo y cómo configurar cada método de autenticación compatible en la especificación de tu API.
¡Lo que intenta!
Desde cualquier página de endpoint en tu referencia de API publicada, los desarrolladores pueden:
- Seleccione un método HTTP y un punto final
- Relleno de parámetros obligatorios y opcionales
- Configurar credenciales de autenticación
- Envía una solicitud en directo y visualiza la respuesta en tiempo real
Try It! no está disponible para webhooks. Las páginas Webhook muestran el esquema de la carga útil y un ejemplo, pero no pueden enviar solicitudes de prueba.
Requisitos para que Try It! aparezca
Try It! solo aparece en una página de endpoint cuando ambos están correctamente definidos en tu archivo de especificaciones de la API:
- Una URL de servidor : la
serverssección de tu especificación debe contener al menos una URL base válida. - Una variable servidor : la variable debe definirse junto a la URL.
Si falta alguno de estos, el botón Pruébalo! no será visible en la página de la base de conocimientos.
Formato correcto de URL del servidor
servers:
- url: https://api.yourdomain.com
description: Production
Para APIs con múltiples regiones, define múltiples entradas:
servers:
- url: https://api.yourdomain.com
description: Global
- url: https://api.us.yourdomain.com
description: US region
Las URLs anteriores son ejemplos. Usa la URL base real de tu API.
Cómo se enrutan las solicitudes
Cuando un desarrollador haga clic en Pruébalo y ve respuesta, la URL de la solicitud aparecerá tryit.document360.io prependida a la URL base de tu API. Por ejemplo:
https://tryit.document360.io/https://api.yourdomain.com/v2/your-endpoint
Este es un comportamiento esperado. El tryit.document360.io subdominio se utiliza internamente para enrutar y procesar solicitudes de prueba de API. No afecta a la funcionalidad, pero las peticiones siguen devolviendo los resultados correctos de tu API.
Métodos de autenticación soportados
Document360 lee la configuración de autenticación directamente de tu especificación OpenAPI y la muestra en dos lugares: la documentación del endpoint y la consola Try It!.
| Método | Cómo funciona |
|---|---|
| Autenticación básica | El nombre de usuario y la contraseña se transmiten en la cabecera de la solicitud. |
| Ficha portadora | Un token generado tras iniciar sesión pasaba en la cabecera de Autorización. |
| Clave API | Una clave única pasaba en las cabeceras de las solicitudes. |
| OAuth2 | Soporta código de autorización, PKCE, credenciales de cliente y flujos implícitos. |
| OpenID Connect | Extiende OAuth2 para añadir la verificación de identidad del usuario. |
Los métodos de autenticación se definen en tu especificación OpenAPI bajo components/securitySchemes y se aplican a puntos finales individuales usando el security campo.
Try It! soporta múltiples sistemas de seguridad simultáneamente. Esto significa que los desarrolladores pueden probar endpoints que requieren métodos de autenticación combinados dentro de la misma sesión.
Autenticación básica
La autenticación básica requiere que se codifiquen y se transmitan un nombre de usuario y una contraseña en la Authorization cabecera de cada solicitud.
En tu especificación de OpenAPI:
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
Aplícalo a un punto final:
/your-endpoint:
get:
security:
- basicAuth: []
En Pruébalo!, se pedirá a los desarrolladores que introduzcan un nombre de usuario y una contraseña antes de enviar una solicitud.
Ficha portadora
La autenticación de token portador utiliza un token pasado en la Authorization cabecera como Bearer <token>.
En tu especificación de OpenAPI:
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
Document360 requiere que el esquema de seguridad sea nombrado BearerAuth (sensible a mayúsculas y minúsculas). Si esta definición falta en tu especificación, hacer clic en Pruébalo! en un endpoint afectado devolverá un error 403. Durante la importación, Document360 marcará esto en la sección de Alertas si detecta una definición faltante de BearerAuth.
Aplícalo a un punto final:
/your-endpoint:
get:
security:
- BearerAuth: []
Clave API
La autenticación de clave API utiliza una clave única que se pasa en las cabeceras de la solicitud.
En tu especificación de OpenAPI:
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
Aplícalo a un punto final:
/your-endpoint:
get:
security:
- ApiKeyAuth: []
En Pruébalo!, se pedirá a los desarrolladores que introduzcan el valor de su clave API. Se enviará con el nombre de cabecera definido en tu especificación (X-API-Key en el ejemplo anterior).
OAuth2
OAuth2 está soportado con cuatro flujos. Utiliza el flujo que coincida con cómo tu API emite los tokens de acceso.
| Flujo | Cuándo usarlo |
|---|---|
| Código de autorización | Aplicaciones del lado del servidor donde el secreto del cliente puede mantenerse confidencial. |
| PKCE | Clientes públicos como aplicaciones de página única y aplicaciones móviles donde el secreto no puede mantenerse confidencial. |
| Credenciales de los clientes | Comunicación máquina a máquina donde no hay ningún usuario involucrado. |
| Implícito | Flujo de legado. No se recomienda para nuevas implementaciones. |
Configuración requerida para Try It!
Cuando tu API utiliza OAuth2, se deben configurar dos ajustes adicionales:
Redirección URI — Tras completar el flujo de autorización OAuth, un desarrollador es redirigido de nuevo a Document360. Añade el URI de redirección de Document360 a la lista de URIs de redirección permitidos de tu proveedor OAuth:
https://your-apidocs-domain.com/oauth
Sustituye your-apidocs-domain.com por el dominio en el que se publica la documentación de la API de Document360.
Renovación silenciosa — Document360 actualiza automáticamente el token de acceso OAuth en segundo plano mientras un desarrollador está usando activamente Try It!. Esto evita que la sesión expire a mitad de uso. No se requiere ninguna configuración por tu parte porque esto se gestiona automáticamente por Document360.
Definición de especificación de ejemplo (Flujo de código de autorización)
components:
securitySchemes:
oauth2Auth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.yourdomain.com/oauth/authorize
tokenUrl: https://auth.yourdomain.com/oauth/token
scopes:
read: Read access
write: Write access
OpenID Connect
OpenID Connect amplía OAuth2 añadiendo la verificación de identidad de usuario. Está configurado de forma similar a OAuth2 y tiene los mismos requisitos de URI de redirección y renovación silenciosa.
En tu especificación de OpenAPI:
components:
securitySchemes:
openIdConnect:
type: openIdConnect
openIdConnectUrl: https://auth.yourdomain.com/.well-known/openid-configuration
Se aplica el mismo requisito de URI de redirección:
https://your-apidocs-domain.com/oauth
Aplicar múltiples esquemas de seguridad a un mismo punto final
Si un endpoint requiere más de un método de autenticación simultáneamente, defíneos juntos bajo security el nivel de operación:
/secure-endpoint:
get:
security:
- BearerAuth: []
ApiKeyAuth: []
Esto requiere que se proporcionen tanto un token portador como una clave API antes de que la solicitud pueda enviarse. Try It! soporta múltiples esquemas de seguridad en una sola sesión.
¿Qué Tryit! no soporta
- Webhooks - Try It! no está disponible para definiciones de webhooks. Las páginas Webhook muestran el esquema de la carga útil y un ejemplo, pero no pueden enviar solicitudes de prueba.
- Respuestas dinámicas basadas en instancias - Document360 sigue la especificación OpenAPI, que define una estructura estática consistente para objetos de solicitud y respuesta. Si tu API devuelve respuestas diferentes para el mismo endpoint en distintos entornos o instancias, Try It! reflejará solo lo que está definido en la especificación.
Preguntas frecuentes
¿Por qué la URL de Pruébalo! incluye tryit.document360.io?
Este es un comportamiento esperado. El tryit.document360.io subdominio se utiliza internamente para enrutar y procesar solicitudes de prueba de API. No afecta a la funcionalidad: las solicitudes siguen devolviendo los resultados correctos de tu API.
¿Puedo probar endpoints que requieren más de un método de autenticación?
Sí. Try It! soporta múltiples sistemas de seguridad simultáneamente. Los desarrolladores pueden configurar y enviar credenciales para múltiples esquemas en una sola solicitud.
¿Puede un agente de IA cambiar entre MCP y la API estándar dentro del mismo flujo de trabajo?
Sí. Un único flujo de trabajo puede usar MCP para los pasos de razonamiento y acción — búsqueda, lectura, escritura y llamar directamente a la API estándar para operaciones fuera del alcance de MCP. Las dos interfaces no son mutuamente excluyentes; acceden a la misma base de conocimiento subyacente.