Cuando construyes documentación para una API o un producto que depende de datos del backend te enfrentas a un reto conocido: cómo hacer que los ejemplos parezcan reales sin depender de un entorno de staging frágil o exponer endpoints de producción. En este artículo explico paso a paso cómo usar Mock Service Worker MSW con Docusaurus para obtener documentación interactiva y consistente, además de mostrar cómo Q2BSTUDIO puede ayudarte a integrar estas prácticas en tus proyectos de software a medida.
Por qué la documentación necesita respuestas de API realistas
¿Cuántas veces seguiste un tutorial de API, pulsaste Run y apareció un error inmediato porque el servidor de staging estaba caído o faltaba un token? Al simular tus APIs consigues consistencia en los ejemplos, un sandbox seguro donde los usuarios pueden probar sin romper nada, menor fricción para nuevos usuarios porque no necesitan claves ni VPNs y la posibilidad de trabajar offline. MSW intercepta peticiones en la capa de red mediante un Service Worker, por eso el frontend no distingue entre APIs reales y simuladas, ideal para documentación interactiva.
Instalación básica
Instala MSW como dependencia de desarrollo con npm install msw --save-dev. Esto añade las herramientas necesarias para arrancar un Service Worker en desarrollo.
Arquitectura recomendada
Pensar la arquitectura antes de codificar ahorra tiempo. Necesitas handlers que definan cada endpoint a simular, un fichero browser.js que arranque MSW en el navegador y opcionalmente un servidor node para reutilizar mocks en tests. Una estructura típica podría ser src/mocks con handlers.js y browser.js, y src/theme/Root.js para iniciar el worker en modo desarrollo.
Handlers y ejemplos
Un handler actúa como un pequeño contrato de API: verbo HTTP, ruta y respuesta. Por ejemplo puedes definir GET en /api/info que devuelva status 200 con un objeto JSON con el mensaje Hello from MSW y un POST en /api/login que simule la creación de un token. Con esto reproduces flujos de login o fetch sin un backend real.
Bootstrap en el navegador
En src/mocks/browser.js se importa setupWorker y los handlers y se crea una única entrada para el Service Worker. Luego en src/theme/Root.js se importa dinámicamente ese browser.js solo en desarrollo y se llama a worker.start pasando onUnhandledRequest en bypass para que las peticiones no mockeadas sigan alcanzando la API real cuando solo mockeas una parte del backend.
Haciendo la documentación interactiva
Incluye componentes React en tus páginas de Docusaurus que hagan fetch a las rutas mockeadas. Así los lectores ven respuestas reales y pueden experimentar con componentes live directamente en la documentación.
Despliegue en GitLab Pages y rutas dinámicas
En GitLab Pages cada pipeline puede generar una URL dinámica, lo que rompe la localización por defecto de mockServiceWorker.js en la raíz. La solución es pasar serviceWorker.url a worker.start calculando la ruta basada en window.location.pathname para apuntar a mockServiceWorker.js en la ubicación correcta del pipeline. Ese pequeño ajuste garantiza que MSW siempre se encuentre en despliegues CI/CD con URLs dinámicas.
Errores comunes y buenas prácticas
Evita problemas CORS asegurando que la URL mockeada coincide exactamente con la solicitud fetch, importa correctamente browser.js en Root.js para que el worker arranque, protege el arranque de MSW con una comprobación de NODE_ENV para que no se ejecute en producción y usa serviceWorker.url cuando tu CI/CD genere rutas dinámicas.
Uso de MSW en tests
MSW permite reutilizar los mismos mocks en pruebas de integración usando setupServer desde msw/node y los mismos handlers. De este modo tus tests, tu entorno de desarrollo y tu documentación hablan el mismo idioma, reduciendo fricción y errores.
Q2BSTUDIO y cómo podemos ayudarte
En Q2BSTUDIO somos una empresa de desarrollo de software que crea aplicaciones a medida y software a medida, especialistas en inteligencia artificial, ciberseguridad y servicios cloud aws y azure. Podemos integrar MSW y Docusaurus en tus procesos de documentación para que tus equipos y clientes dispongan de guías interactivas y reproducibles. Si necesitas desarrollar una plataforma con documentación interactiva y pruebas end to end, consulta nuestros servicios de desarrollo de aplicaciones a medida o aprovecha nuestras soluciones de inteligencia artificial para empresas para añadir agentes IA y automatizaciones inteligentes a tu producto.
Palabras clave y servicios
Implementar MSW en Docusaurus mejora la experiencia de usuario y la calidad del aprendizaje sobre APIs, y encaja con servicios de inteligencia de negocio y Power BI para documentar y mostrar datos reales en ejemplos. En Q2BSTUDIO combinamos experiencia en ia para empresas, agentes IA, ciberseguridad, servicios cloud aws y azure y servicios inteligencia de negocio para ofrecer soluciones completas que van desde la arquitectura de backend hasta la documentación interactiva y los pipelines CI/CD.
Conclusión
Simular APIs en tu sitio Docusaurus no es un añadido opcional, es una mejora profesional que separa documentación razonable de documentación extraordinaria. Con MSW obtienes respuestas con apariencia de producción sin los riesgos de producción, tus usuarios aprenden más rápido y tu equipo invierte menos tiempo en resolver problemas de documentación. Si quieres asesoramiento práctico o integración completa, en Q2BSTUDIO podemos acompañarte en todo el proceso.
