Servir asset de Docs
Comprueba que una imagen o vídeo de documentación se entrega como archivo estático desde Docs. La URL puede ser pública o autenticada y apunta a un fichero existente bajo la raíz de assets configurada; la respuesta correcta es el binario del recurso, no un JSON de negocio.
En este artículo
Use esta guía cuando necesite validar que un recurso publicado en la documentación carga desde `/api/public/docs/assets/{path}` o desde `/api/app/docs/assets/{path}`.
La variante de media se decide al consultar el artículo con `locale`, `platform` y `theme`; la descarga directa del asset solo depende del path que aparece después de `/assets/`.
Antes de empezar
- Las rutas de Docs están registradas en el backend de Antylogic.
- El fichero solicitado existe bajo `DOCS_ASSETS_PATH`, `DocsRoutesConfig.AssetsPath` o el directorio de assets por defecto.
- Para `/api/app/docs/assets/{path}` hay una sesión válida; `/api/public/docs/assets/{path}` no requiere iniciar sesión.
- La URL suele obtenerse desde `article.media[].src` en el detalle del artículo de documentación.
Instrucciones
- 1.
Localiza la URL del recurso en el artículo
Abre o consulta el artículo que contiene la imagen o vídeo. En `media.src`, Antylogic ya habrá aplicado el prefijo correcto y la variante de plataforma y tema, por ejemplo `/api/public/docs/assets/iphone/light/es/...` para una consulta pública en móvil y tema claro.
- 2.
Abre el asset público si no requiere sesión
Usa la URL pública para confirmar que el recurso publicado está disponible sin autenticación. Un ejemplo actual es `/api/public/docs/assets/iphone/light/es/auth-native-login/auth-native-login-validation-clip.mp4`; debe mostrarse o descargarse como vídeo, sin página de aplicación ni JSON de negocio.
- 3.
Valida la ruta autenticada desde la app
En la app, con la sesión Demo Marea activa en Grupo Marea Demo, `DocumentationPage` solicita la media con el prefijo `/api/app/docs/assets/...`. Si falta la cookie o el token, la petición se rechaza antes de llegar al servicio de Docs.
- 4.
Interpreta los errores de publicación
Si el asset no carga, revisa el segmento posterior a `/assets/`. `400` apunta a ruta inválida o traversal bloqueado, `404` a fichero ausente, directorio o path vacío, `405` a método no permitido y `503` a Docs no configurado.
Validaciones y límites
- `media.src` empieza por `/api/public/docs/assets/` o `/api/app/docs/assets/`.
- La descarga directa del asset no cambia por añadir `locale`, `platform`, `device`, `theme` o `q`.
- El endpoint admite `GET` y también `HEAD`, aunque la wiki documente principalmente `GET` para assets.
- La ruta pública puede exponer cualquier fichero colocado bajo la raíz configurada de assets; esa raíz no debe incluir material no publicable.
- La ruta autenticada solo añade autenticación general de sesión, sin permisos granulares por organización, ubicación o rol.
- El endpoint puede servir ficheros existentes aunque no estén referenciados por `articles.json`.
Resultado esperado
El operador confirma que la documentación resuelve una URL de asset válida y que el backend sirve el fichero estático desde la ruta pública o autenticada correspondiente.