Documentación y consolas expuestas

Esconder la documentación no protege una API: quien quiera entenderla puede observar el tráfico de la aplicación oficial. El problema no es que exista, sino lo que se publica de más. El contrato que genera un framework suele incluirlo todo: operaciones de administración, rutas internas que solo llama otro servicio, servidores de red interna que no pasan por la pasarela, ejemplos copiados de datos reales. Cada una de esas cosas le ahorra trabajo a quien busca una puerta.

La otra pieza es la consola interactiva, la página con un botón para enviar peticiones de prueba desde el navegador. En un entorno de pruebas es útil. En producción convierte la documentación en un cliente de la API real, con la sesión de quien la abre y contra datos reales.

Abre el laboratorio y lee config-documentacion.txt. Cada servicio declara si publica su documentación, si la publica con consola interactiva y si filtra las operaciones internas. Lo que importa es la combinación de esos ajustes con el entorno. Confírmalo con inventario-documentacion.txt.

El bloque servers de un contrato dice contra qué direcciones se llama la API, y la consola interactiva lo ofrece como lista para elegir. Lee openapi-domicilios.json. Uno de los servidores declarados no es la dirección pública: es la del servicio en la red interna, y su propia descripción dice qué se salta.

El servicio de domicilios publica el contrato «tal como lo genera el framework». Las etiquetas (tags) de cada operación dicen para quién es: clientes, repartidores, o uso interno y de administración. Cuenta las operaciones del contrato publicado que no son para nadie de fuera de Tasajera, es decir, las etiquetadas como de administración o de uso interno.

El equipo de domicilios no quiere perder la documentación, que usan los repartidores y la aplicación de socios. La corrección tiene que dejar lo útil y quitar lo que sobra, y el resto de servicios de Tasajera ya muestra cómo se hace.