Saltar a contenido

0066. Documentación de la API apagada por defecto

Estado: Aceptado
Fecha: 2026-11-11
Módulo(s) afectado(s): app/core/config.py, app/main.py, tests/

Contexto

FastAPI publica por defecto /docs (Swagger UI), /redoc y /openapi.json. Este servicio firma los JWT de toda la plataforma, y /openapi.json expone la estructura completa de su API: rutas administrativas, parámetros y esquemas. En producción esa información solo le sirve a quien busca superficie de ataque.

La configuración ya tenía ENVIRONMENT (default "local"), pero su valor por defecto no es seguro y su significado es más amplio que la documentación.

Decisión

  • Se agrega API_DOCS_ENABLED (api_docs_enabled: bool = False en Settings), una variable dedicada solo a la documentación.
  • Con False, que es el default, create_app() construye FastAPI con docs_url=None, redoc_url=None y openapi_url=None: las tres rutas responden 404. Se anula también openapi_url porque apagar solo las UI dejaría el esquema completo publicado.
  • Con True se publican las tres rutas, como antes.
  • DEBUG no cambia: ya es False por defecto y ningún código lo enciende.

Alternativas descartadas

  • Comparar ENVIRONMENT == "development": un valor mal escrito (develop, dev) apagaría o encendería la documentación sin aviso. Un booleano mal escrito (ture) falla al arrancar.
  • Agregar una variable ENV nueva: duplicaría ENVIRONMENT.

Consecuencias

  • Un despliegue que no declara la variable no expone la documentación.
  • En local hay que declarar API_DOCS_ENABLED=true en el .env para ver /docs.
  • tests/conftest.py siembra API_DOCS_ENABLED=true con setdefault, porque varias pruebas leen /openapi.json para inspeccionar las rutas montadas.
  • Verificación en producción: GET /docs, GET /redoc y GET /openapi.json deben responder 404.