Comprobar Docs con HEAD
Comprueba de forma ligera que los índices de documentación responden en `HEAD /api/public/docs` y `HEAD /api/app/docs` con `200 OK` sin cuerpo. Esta acción no valida artículos, assets, filtros de idioma ni la frescura de `articles.json`.
En este artículo
Usa esta guía cuando soporte o implantación necesiten confirmar que la ayuda integrada está disponible sin cargar el contenido de documentación.
La ruta pública no requiere sesión. La ruta de aplicación exige una sesión válida con `Authorization: Bearer` o cookie `access_token`, pero no aplica permisos granulares adicionales de documentación.
Antes de empezar
- El servidor debe estar desplegado con las rutas de documentación registradas.
- Para `HEAD /api/public/docs` no hace falta iniciar sesión.
- Para `HEAD /api/app/docs` hace falta una sesión válida mediante `Authorization: Bearer` o cookie `access_token`.
- No hace falta que `backend/docs-content/articles.json` exista o esté actualizado para que el `HEAD` de índice responda, porque este flujo no carga contenido.
Instrucciones
- 1.
Elegir el índice que se quiere comprobar
Usa `HEAD /api/public/docs` para validar la disponibilidad pública del índice de ayuda. Usa `HEAD /api/app/docs` para validar la ruta de ayuda autenticada desde una sesión operativa. No apliques esta comprobación a rutas de assets como `/api/app/docs/assets/{path}` o `/api/public/docs/assets/{path}`.
- 2.
Enviar la petición con método HEAD
La llamada debe ejecutarse con método `HEAD`. Si el servicio de documentación está configurado, el resultado esperado es `200 OK` sin JSON, sin secciones, sin `article_count` y sin detalle de artículos.
- 3.
Interpretar errores comunes
Si `/api/app/docs` responde error de autenticación, revisa que el Bearer token o la cookie `access_token` sigan siendo válidos. Un token validado sin `UserID` produce `401 token invalido`. Un método distinto de `GET` o `HEAD` produce `405 metodo no permitido`. Si la documentación no está configurada en el servidor, la respuesta esperada es `503 documentacion no configurada`.
- 4.
Usar GET para validar contenido
Cuando necesites confirmar secciones, artículos localizados, media, búsqueda o el estado real de `articles.json`, usa `GET /api/public/docs` o `GET /api/app/docs`. `HEAD` solo confirma que la ruta de índice responde y no aplica el `Cache-Control` de `docsContentService`.
Validaciones y límites
- La respuesta correcta del flujo principal es `200 OK` sin cuerpo.
- `HEAD /api/public/docs` y `HEAD /api/app/docs` funcionan como comprobación ligera de disponibilidad de ruta, no como validación del bundle de documentación.
- Los parámetros `locale`, `platform`, `device`, `theme` y `q` no se validan en esta acción; pertenecen a los flujos `GET`.
- El código actual también puede devolver `200` para `HEAD` en subrutas no asset de docs, pero la documentación operativa solo debe anunciar `HEAD` para `/api/public/docs` y `/api/app/docs`.
- No hay una prueba dedicada para `HEAD /api/public/docs` o `HEAD /api/app/docs`; la prueba existente cubre `GET` de índice, `GET` de detalle y `GET` de asset.
Resultado esperado
La disponibilidad básica de los índices de documentación queda verificada sin cargar `articles.json`, sin devolver cuerpo y sin producir capturas visuales.