agatha
602648ef56
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>
41 lines
1.5 KiB
Markdown
41 lines
1.5 KiB
Markdown
# 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.
|