Listar el índice público de Docs
Usa el índice público de Docs para confirmar que la experiencia de Docs de la landing puede cargar resúmenes de guías agrupados para el locale resuelto, con filtrado opcional en el servidor para comprobaciones directas de la API.
En este artículo
Esta guía cubre el índice de documentación público y de solo lectura que usan la página de Docs de la landing y los consumidores directos de JSON a través de GET /api/public/docs.
El endpoint agrupa los resúmenes de artículo en secciones de documentación para el locale resuelto. No requiere inicio de sesión, contexto de organización, contexto de ubicación, pertenencia a un rol ni cuerpo de petición.
Antes de empezar
- El servicio de documentación público está registrado y el bundle de contenido de docs es legible desde DOCS_CONTENT_PATH o ./docs-content/articles.json.
- Usa GET para la petición de índice. La acción no lee cuerpo de petición.
- Para el contexto de documentación en español de ES, usa locale=es-ES o locale=es; la respuesta informa el locale como es.
- Para capturas, usa APP_WEB_URL=/docs?lang=es para la página de la landing y PUBLIC_API_BASE_URL para las respuestas directas de la API.
Instrucciones
- 1.
Abre el índice público de docs
Abre /docs?lang=es o llama a GET /api/public/docs?locale=es&platform=mobile&theme=light. Un GET correcto devuelve HTTP 200 con version, locale, platform, article_count y sections.
- 2.
Revisa las secciones y los resúmenes
Comprueba el array sections. Cada sección representa una categoría de documentación, y cada resumen de artículo identifica la guía con id, slug, section_slug, action_id opcional, primary_keyword opcional, title, summary, icon_name y has_media.
- 3.
Comprueba el filtrado opcional
Para comprobaciones directas de la API, añade q. Por ejemplo, GET /api/public/docs?locale=es-ES&device=iphone&q=reservas resuelve el locale a es, el dispositivo a la plataforma mobile y devuelve solo los resúmenes coincidentes.
- 4.
Lee las variantes y los límites
Usa platform o device solo para solicitar el contexto de contenido previsto. El parser de opciones compartido acepta theme, pero la respuesta del índice no lo devuelve porque la resolución de media pertenece al detalle del artículo.
Validaciones y límites
- GET devuelve HTTP 200 cuando el servicio de docs y el fichero de contenido están disponibles.
- article_count es igual al número de resúmenes de artículo devueltos tras el filtrado por locale y q.
- Un valor de q sin coincidencias sigue devolviendo HTTP 200, article_count: 0 y un array sections vacío.
- La caja de búsqueda de Docs de la landing filtra los resúmenes ya cargados en el cliente; no debe documentarse como si enviase q.
- Solo se aceptan GET y la comprobación HEAD hermana. HEAD /api/public/docs no demuestra que articles.json pueda cargarse.
Resultado esperado
La página pública de Docs y los consumidores directos de la API pueden verificar el índice de documentación no autenticado, inspeccionar los resúmenes de artículo agrupados y confirmar la normalización de locale, platform y q sin tocar datos de inquilino.