Files

agatha 602648ef56 Feat: Gate API docs endpoints behind API_DOCS_ENABLED env var

When API_DOCS_ENABLED=false, FastAPI registers no routes for /docs,
/redoc, or /openapi.json, returning 404 for all three. Default is true
for backwards compatibility. Invalid values fall back to true (FR-007).

Fix: Remove tests/ and alembic/ from api/.dockerignore so the test
Dockerfile (which uses COPY . .) includes the test suite; Dockerfile.prod
is unaffected as it only copies app/ explicitly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-07 20:40:48 +00:00

1.5 KiB

Raw Blame History

Contract: API Documentation Endpoints

These three endpoints exist in FastAPI by default. This feature makes their availability conditional on a runtime configuration flag.

Affected Endpoints

Endpoint	Default path	Purpose
Swagger UI	`GET /docs`	Interactive browser-based API documentation
ReDoc UI	`GET /redoc`	Alternative read-only API documentation
OpenAPI schema	`GET /openapi.json`	Raw JSON schema of the entire API surface

Behaviour by Flag State

`API_DOCS_ENABLED=true` (default)

All three endpoints respond exactly as they did before this feature. No change.

Endpoint	Response
`GET /docs`	`200 OK` — Swagger UI HTML
`GET /redoc`	`200 OK` — ReDoc UI HTML
`GET /openapi.json`	`200 OK` — OpenAPI schema JSON

`API_DOCS_ENABLED=false`

All three endpoints are unregistered. Requests fall through to the framework's default 404 handler.

Endpoint	Response
`GET /docs`	`404 Not Found`
`GET /redoc`	`404 Not Found`
`GET /openapi.json`	`404 Not Found`

Invariants

All other endpoints are unaffected in both flag states.
The GET /api/v1/health endpoint always returns 200 OK regardless of the flag.
Internal OpenAPI schema generation (used for request/response validation) is not disabled — only the HTTP routes serving it are removed.
The flag is read once at application startup. A running process does not respond to live changes; a restart is required.

1.5 KiB Raw Blame History