Cuando abres un documento de API en línea publicado usando Apidog, notarás un botón "Probar" junto a cada endpoint. Al hacer clic en él, se desliza un panel de depuración en el lado derecho de la página, lo que te permite probar la API directamente dentro de la documentación.
Sin embargo, la usabilidad de esta función de "Depuración" depende en gran medida de lo bien que la hayas configurado dentro de la plataforma. Factores como una configuración de URL adecuada, la configuración de autenticación, una estructura de parámetros clara y datos de ejemplo completos impactan significativamente la experiencia de depuración.
Si no se configura correctamente, los usuarios pueden pasar mucho tiempo rellenando parámetros o incluso fallar al realizar llamadas a la API con éxito, lo cual está lejos de ser ideal.
Analicemos cómo configurar Apidog de manera efectiva para asegurar que la documentación en línea publicada proporcione una excelente experiencia de depuración.
Configuración de URL Adecuada
A menudo, la documentación en línea se ve bien, pero falla cuando haces clic en el botón "Probar" para enviar una solicitud. La razón más común es que el endpoint solo incluye una ruta como /pet/{petId} sin seleccionar un entorno de ejecución durante la publicación.
Esto resulta en URLs de solicitud incompletas sin un protocolo o nombre de host, lo que lleva a errores al enviar solicitudes.
Para solucionar esto, asegúrate de que los usuarios puedan acceder a la URL correcta. Apidog ofrece tres formas de configurar URLs para la documentación en línea, dependiendo de tus necesidades.
1. Usar URLs Base
Este es el enfoque recomendado. Define solo la ruta en el endpoint, como /pet/{petId}, y configura la dirección de servicio completa (por ejemplo, https://product.example.com) en la sección "Gestión de Entornos" como una URL Base.
Al publicar la documentación de la API, selecciona el entorno de ejecución apropiado. Apidog concatenará automáticamente la URL Base con la ruta del endpoint. También puedes definir múltiples entornos de ejecución, cada uno con su propia URL Base.
En la documentación en línea, los usuarios pueden cambiar rápidamente de entorno desde una lista desplegable, y todas las URLs de los endpoints se actualizarán en consecuencia. Esto hace que sea conveniente validar APIs en diferentes entornos.
Nota: Ten en cuenta los problemas de protocolo. Muchos navegadores restringen que las páginas HTTPS llamen a APIs HTTP. Si tu API usa HTTP, los usuarios pueden encontrar problemas de protocolo cruzado al depurar en una página de documentación HTTPS.
2. Incluir URLs Completas en los Endpoints
Otra opción es especificar la URL completa directamente en el endpoint, como https://product.example.com/pet/{petId}.
Esto asegura que la URL de solicitud completa sea visible independientemente del entorno de ejecución seleccionado. Sin embargo, gestionar los cambios en las direcciones del servidor se vuelve engorroso, ya que deberás actualizar cada endpoint individualmente. Por lo tanto, este método es menos recomendado.
3. Usar Variables en las URLs
Si quieres que los usuarios personalicen la URL para la depuración, puedes usar variables. Por ejemplo, crea una variable de entorno BaseURL en la sección "Gestión de Entornos" y referénciala en la URL Base como {{BaseURL}}.
En la documentación en línea, los usuarios pueden hacer clic en el nombre de la variable y modificarla a la URL deseada.
Alternativamente, puedes definir variables directamente en el endpoint, como {{BaseURL}}/pet/{petId}.
Para ese endpoint específico en la documentación en línea, los usuarios pueden establecer el valor de la variable para enviar la solicitud.
Antes de publicar la documentación, asegúrate de que los "valores iniciales" en el entorno no contengan información sensible (por ejemplo, credenciales de autenticación), ya que estos valores se incluirán en la documentación publicada y pueden suponer riesgos de privacidad.
Configuración de Autenticación Adecuada
Configuración de Autenticación Básica
Las solicitudes de endpoint exitosas a menudo requieren autenticación. Apidog soporta varios tipos de autenticación, incluyendo Bearer Token, API Key, OAuth2.0 y Basic Auth.
Puedes configurar la autenticación a nivel de endpoint o de carpeta usando un esquema de seguridad o configurándola manualmente.
Por ejemplo, al usar Bearer Token como tipo de autenticación, aparece un campo "Token" en la parte superior del panel de depuración en la documentación en línea. Los usuarios pueden introducir el valor del token directamente sin añadir manualmente el prefijo "Bearer". Apidog lo maneja automáticamente, lo que lo hace más conveniente que añadir un encabezado de autorización manualmente.
La ventaja de esta configuración es que la información de autenticación se puede compartir entre múltiples endpoints. Si varios endpoints usan el mismo esquema o tipo de seguridad, solo necesitas introducir las credenciales una vez. Cualquier actualización de las credenciales se aplicará automáticamente a todos los endpoints asociados.
Las credenciales de autenticación se cifran y se almacenan localmente en el navegador del usuario, se gestionan por sesión y se comparten entre pestañas y ventanas. Se borran cuando se cierra el navegador, lo que reduce el riesgo de exponer información sensible en la documentación publicada.
Configuración de OAuth2.0
Para la autenticación OAuth2.0, si quieres que los usuarios generen tokens directamente durante la depuración, configura los detalles del servidor de autorización (por ejemplo, URL de Autorización, URL de Token) en el proyecto.
Al usar el esquema de seguridad OAuth2.0, los usuarios deberán introducir el ID de cliente, el secreto de cliente, etc., durante la depuración. Una ventana emergente los guiará a través del proceso de autorización, y el access_token obtenido se aplicará automáticamente a las solicitudes de API posteriores.
Diseñar Estructuras de Parámetros Claras
Visualización de Parámetros en el Panel de Depuración
El panel de depuración muestra inteligentemente las secciones de parámetros basándose en el diseño de tu endpoint. Por ejemplo, si el endpoint solo define parámetros de Ruta, el panel de depuración solo mostrará la sección de Ruta, evitando secciones de Consulta o Cuerpo innecesarias.
Esta claridad ayuda a los usuarios a entender qué parámetros deben rellenar sin distraerse con secciones irrelevantes.
Proporcionar Ejemplos
Al diseñar endpoints, define el tipo de cada parámetro y los atributos requeridos con precisión. Incluye descripciones y ejemplos claros, ya que estos se rellenarán previamente en el panel de depuración, mejorando la usabilidad.
Evitar Encabezados Redundantes
Si el endpoint define parámetros de Cuerpo, no es necesario añadir manualmente encabezados como Content-Type: application/json. Apidog maneja automáticamente dichos encabezados durante las solicitudes.
De manera similar, si la autenticación está configurada, evita duplicarla en los encabezados. La configuración de autenticación tiene prioridad y anulará cualquier configuración de encabezado conflictiva.
Ofrecer Ejemplos de Solicitud Completos
Para endpoints con cuerpos de solicitud JSON complejos, proporciona múltiples ejemplos de cuerpos de solicitud durante el diseño.
Los usuarios pueden seleccionar estos ejemplos de un menú desplegable en el panel de depuración, ahorrando tiempo y reduciendo errores.
Asegúrate de que los datos de ejemplo se parezcan mucho a escenarios del mundo real, pero evita incluir información sensible. Los usuarios pueden modificar estos ejemplos según sea necesario.
Configurar Ejemplos de Respuesta Claros
Después de enviar una solicitud, el panel de depuración muestra la respuesta completa, incluyendo códigos de estado, encabezados y cuerpo. Como creador de documentación, configura ejemplos de respuesta claros para ayudar a los usuarios a comprender los posibles resultados.
Proporciona múltiples ejemplos de respuesta para cada endpoint, como éxito (200), solicitud incorrecta (400) y no autorizado (401).
Presta especial atención a las respuestas de error, explicando claramente los códigos de error y los formatos de mensaje para diferentes escenarios. Esto ayuda a los usuarios a identificar y resolver problemas rápidamente durante la depuración.
Proporcionar Código de Ejemplo para la Integración
Aunque Apidog genera automáticamente código de ejemplo para lenguajes de programación comunes, el código generado puede no alinearse completamente con tus necesidades comerciales. En tales casos, personaliza los ejemplos.
Puedes configurar qué lenguajes requieren ejemplos autogenerados en "Configuración del Proyecto -> Configuración de Funciones del Endpoint -> Ejemplos de Código de Solicitud".
Además, puedes escribir código de ejemplo personalizado para endpoints específicos en la sección "Descripción del Endpoint".
Esto asegura que los usuarios vean tanto ejemplos autogenerados como personalizados en la documentación en línea, facilitando la integración.
Resumen
La experiencia de depuración de la documentación en línea depende en gran medida de una configuración adecuada. Al configurar cuidadosamente las URLs, la autenticación, las estructuras de parámetros y los ejemplos, puedes asegurar que los usuarios comiencen rápidamente con tu API sin atascarse en detalles técnicos.