Endpoint /api/openapi-export — Export OpenAPI con Bearer auth

Entidadactivecreado Tue May 05#biblioteca #api #security #django #infra #multi-tenancy #observability #supercontext

Descripción

GET /api/openapi-export es un endpoint interno de Django Ninja registrado en config/urls.py que devuelve el schema OpenAPI completo de la API de CreaRack Pro. Fue introducido en s50 (05-05-2026) para resolver el OOM (rc=137) que ocurría al extraer el schema mediante docker exec en el servidor STAGE CX23 (4 GB de RAM).

El endpoint no expone datos de usuario ni secrets: devuelve exclusivamente la estructura de la API (equivalente a lo que mostraría /api/docs Swagger UI si estuviera habilitado).

Autenticación: `_InternalToolsAuth`

class _InternalToolsAuth(HttpBearer):
    def authenticate(self, request, token):
        expected = (os.environ.get("INTERNAL_TOOLS_TOKEN") or "").strip()
        if not expected or len(expected) < 32:
            return None  # deny all si no hay token o es muy corto
        if token == expected:
            return token
        return None

Propiedad	Valor
Tipo	`HttpBearer` (Django Ninja)
Variable de entorno	`INTERNAL_TOOLS_TOKEN`
Longitud mínima del token	32 caracteres
Comportamiento sin token configurado	Deny all (falla segura)
Tag Ninja	`["meta"]`

La clase es privada (_InternalToolsAuth) — no forma parte de la API pública del módulo.

Registro en urls.py

@api.get("/openapi-export", auth=_InternalToolsAuth(), tags=["meta"])
def openapi_export(request):
    """Export OpenAPI schema for internal tools (Biblioteca indexer, etc.)."""
    return api.get_openapi_schema()

Registrado directamente en config/urls.py, fuera de cualquier router específico de app, junto al resto de routers de primer nivel (/backup, /metrics, etc.).

Consumidores previstos

Consumidor	Modo
`scripts/bib_openapi.py`	HTTP GET con `Authorization: Bearer <token>`
Futuros generadores de cliente OpenAPI	HTTP GET
Linters de schema	HTTP GET
`cron-bib-reindex.sh --extras-only`	Vía `bib_openapi.py --push`

Configuración en producción

Generar token: python -c "import secrets; print(secrets.token_urlsafe(48))"
Añadir INTERNAL_TOOLS_TOKEN=<token> en panel Dokploy → app crearack-pro.
En STAGE: echo "<token>" > /opt/bib-reindex/.token-internal && chmod 600 /opt/bib-reindex/.token-internal
Verificar: curl -H "Authorization: Bearer <token>" https://crearack.com/api/openapi-export

Para el procedimiento completo de despliegue, ver el runbook asociado.

Seguridad

Sin acceso a base de datos ni sesión de usuario.
Token mínimo de 32 caracteres; si INTERNAL_TOOLS_TOKEN no está seteado o es corto, el endpoint devuelve 401 deny-all (no hay fallback inseguro).
El archivo .token-internal en STAGE debe tener permisos chmod 600.
No aparece en /api/docs Swagger UI (que no está habilitado en producción).

Véase también

[[feature—biblioteca—bib-openapi-http-mode]]
[[runbook—infra—deploy-internal-tools-token]]
[[entity—api—script—bib-openapi]]