Configurar las rutas de runtime de Docs
Configura el runtime del backend para que Antylogic lea el bundle de docs desde `DOCS_CONTENT_PATH`, sirva la media referenciada desde `DOCS_ASSETS_PATH` y aplique cabeceras de caché separadas al JSON de docs y a los assets de media.
En este artículo
Usa esta guía cuando un operador o responsable de documentación necesite apuntar los Docs de Antylogic al bundle de runtime correcto. Es una tarea de configuración de arranque del backend, no un ajuste de la app.
El mismo servicio de docs sirve la API pública de Docs de la landing y la pantalla autenticada de Docs de la app. Los docs públicos se pueden leer intencionadamente sin autenticación de la app; los docs de la app siguen requiriendo una petición de la app con sesión iniciada.
Antes de empezar
- Acceso al entorno de despliegue o de runtime del proceso del backend.
- `DOCS_CONTENT_PATH` apunta a un fichero `articles.json` o a un directorio que contiene `articles.json`.
- `DOCS_ASSETS_PATH` apunta a la raíz que contiene las rutas de media referenciadas por las entradas de artículo.
- El proceso del backend se inicia o reinicia después de fijar los valores `DOCS_*`.
- Para la verificación autenticada, usa la sesión demo de ES de Grupo Marea Demo y Marea Gran Via.
Instrucciones
- 1.
Prepara el bundle de docs
Coloca el contenido de docs generado y la media donde el backend pueda leerlos. Los valores locales por defecto son `./docs-content` para el contenido y `../frontend/landingpage/public/product-screenshots/docs` para los assets; las imágenes empaquetadas de la API REST y de Lambda incluyen directorios de docs empaquetados salvo que se suministren montajes de runtime equivalentes.
- 2.
Fija los valores de runtime antes del arranque
Fija `DOCS_CONTENT_PATH`, `DOCS_ASSETS_PATH`, `DOCS_CACHE_CONTROL_DEFAULT` y `DOCS_CACHE_CONTROL_ASSETS` en el entorno de runtime del backend. Deja un valor sin fijar solo cuando el valor por defecto implementado sea aceptable.
- 3.
Reinicia el backend
Inicia o reinicia el backend después de fijar el entorno. El registro de rutas crea un único servicio de contenido de docs y lo monta bajo `/api/public/docs` y `/api/app/docs`; solo cambia el prefijo de URL de assets generado.
- 4.
Verifica los docs públicos
Llama a `/api/public/docs` y a una ruta de artículo en español sin autenticación de la app. Para el plan de capturas de ES, usa `/api/public/docs/asistencia/es-ver-panel-de-asistencia?locale=es&platform=mobile&theme=light` y confirma que se devuelve el artículo del tablero de fichaje.
- 5.
Verifica los docs autenticados de la app
Con el usuario demo con sesión iniciada, abre `antylogic://docs/asistencia/es-ver-panel-de-asistencia`. La pantalla nativa de Docs debe cargar el mismo bundle configurado a través de `/api/app/docs`.
- 6.
Comprueba la resolución de assets de media
Abre un artículo que contenga media y confirma que cada `src` se reescribe al prefijo de API activo. Los artículos públicos usan `/api/public/docs/assets/{path}`; los artículos autenticados de la app usan `/api/app/docs/assets/{path}`.
- 7.
Gestiona los fallos habituales
Usa los códigos de estado para separar problemas de configuración de problemas de búsqueda: el contenido ausente devuelve `503`, el JSON inválido devuelve `500`, los métodos no soportados devuelven `405`, los artículos ausentes devuelven `404` y la media ausente devuelve `404` desde la ruta de assets.
Validaciones y límites
- Las sobreescrituras de configuración de rutas en blanco o solo con espacios se ignoran antes de seleccionar los valores por defecto.
- Una ruta de contenido que termina en `.json` se usa directamente; cualquier otra ruta de contenido se trata como un directorio que contiene `articles.json`.
- Los valores de cache-control sin fijar caen a `public, max-age=60` para JSON y a `public, max-age=31536000, immutable` para assets.
- Las respuestas JSON de Docs usan `DOCS_CACHE_CONTROL_DEFAULT` cuando el valor resuelto no está vacío.
- Las respuestas de assets de Docs usan `DOCS_CACHE_CONTROL_ASSETS` cuando el valor resuelto no está vacío.
- Las rutas de assets se limpian, no pueden salir de `DOCS_ASSETS_PATH`, deben existir y no deben ser directorios.
- Una respuesta `HEAD` correcta que no sea de assets no demuestra que el bundle o el artículo existan, porque no carga el fichero de contenido.
Resultado esperado
Tras la configuración, la API pública de Docs y la pantalla autenticada de Docs de la app leen el mismo bundle de docs configurado, la media se resuelve a través de la ruta activa de assets de docs, y el JSON y los assets reciben sus políticas de caché configuradas.