Comprobar un endpoint de Docs con HEAD
Usa HEAD en los endpoints de índice de docs soportados para confirmar que la ruta de docs, el registro del servicio y, para el endpoint de la app, las puertas de autenticación son alcanzables. Una comprobación correcta devuelve 200 OK sin cuerpo JSON y no carga el bundle de contenido de docs.
En este artículo
Usa esta guía cuando los equipos de operaciones, los consumidores de la API o los administradores de monitorización necesiten una comprobación ligera de alcanzabilidad de los endpoints de documentación de Antylogic.
Usa el endpoint público cuando el monitor solo necesite demostrar la alcanzabilidad de la ruta y del servicio de docs. Usa el endpoint de la app cuando el monitor deba confirmar además que una sesión autenticada del usuario demo supera la autenticación y la puerta de cuenta.
Antes de empezar
- La API del backend está en ejecución con las rutas de docs registradas mediante RegisterRoutes y DocsRoutesConfig.
- Para la comprobación pública, usa HEAD /api/public/docs; no se requiere sesión de usuario.
- Para la comprobación de la app, usa HEAD /api/app/docs con un Authorization: Bearer token válido o una cookie access_token de una cuenta no pendiente de eliminación.
- Usa solo las rutas de índice de docs que no son de assets. Las rutas bajo /assets usan reglas de servicio de ficheros independientes.
Instrucciones
- 1.
Elige el endpoint
Usa HEAD /api/public/docs para una comprobación de alcanzabilidad de la ruta pública y del servicio de docs. Usa HEAD /api/app/docs cuando la comprobación deba demostrar además que una sesión válida de la app llega al handler de docs tras la autenticación y la puerta de cuentas pendientes de eliminación.
- 2.
Envía la petición HEAD
Envía una petición HTTP HEAD al endpoint de índice elegido. No esperes JSON, datos de artículo, metadatos de media ni ningún cuerpo de respuesta de una comprobación correcta.
- 3.
Interpreta el 200 OK
Trata el 200 OK como una señal de alcanzabilidad de la ruta y del servicio de docs. Para HEAD /api/app/docs, confirma además que la sesión proporcionada superó la autenticación y la puerta de cuenta.
- 4.
Gestiona los rechazos
Para HEAD /api/app/docs, renueva o sustituye las credenciales ausentes o inválidas. Si la cuenta está pendiente de eliminación, recupérala antes de usarla para esta comprobación. Si el servicio devuelve no disponible, verifica la configuración de rutas de docs antes de investigar el contenido de los artículos.
- 5.
Mantén el alcance acotado
No uses esta acción como comprobación de salud del contenido. Usa GET /api/public/docs o GET /api/app/docs cuando necesites validar el índice de docs, los payloads de artículo, la gestión de locale, las opciones de búsqueda o la disponibilidad de media.
Validaciones y límites
- El handler de docs solo acepta GET y HEAD; el resto de métodos devuelven 405 con metodo no permitido.
- Si el servicio de docs no está configurado, el handler devuelve 503 con documentacion no configurada.
- HEAD /api/app/docs se detiene antes del handler de docs cuando las credenciales faltan, son inválidas o resuelven a un UserID vacío.
- Una cuenta pendiente de eliminación se bloquea antes del handler de docs porque docs no está en la lista de permitidos de la puerta de cuenta.
- Un HEAD genérico correcto no carga backend/docs-content/articles.json y no demuestra que exista un slug de artículo o un asset de docs.
Resultado esperado
El monitor recibe una señal ligera de solo estado. Las comprobaciones públicas demuestran que la ruta y el servicio de docs son alcanzables; las comprobaciones autenticadas de la app demuestran además que la sesión proporcionada supera la autenticación y la puerta de cuenta.