# 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.