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 = FalseenSettings), una variable dedicada solo a la documentación. - Con
False, que es el default,create_app()construye FastAPI condocs_url=None,redoc_url=Noneyopenapi_url=None: las tres rutas responden404. Se anula tambiénopenapi_urlporque apagar solo las UI dejaría el esquema completo publicado. - Con
Truese publican las tres rutas, como antes. DEBUGno cambia: ya esFalsepor 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
ENVnueva: duplicaríaENVIRONMENT.
Consecuencias¶
- Un despliegue que no declara la variable no expone la documentación.
- En local hay que declarar
API_DOCS_ENABLED=trueen el.envpara ver/docs. tests/conftest.pysiembraAPI_DOCS_ENABLED=trueconsetdefault, porque varias pruebas leen/openapi.jsonpara inspeccionar las rutas montadas.- Verificación en producción:
GET /docs,GET /redocyGET /openapi.jsondeben responder404.