API Documentation Guidelines (DRF + drf-spectacular)
=====================================================

Purpose
-------
Create API docs that stay accurate, machine-readable for AI/codegen, and human-friendly without maintaining large, stale Markdown lists.

Principles
----------
- **Source of truth:** drf-spectacular OpenAPI schema generated from code; avoid duplicating endpoints in Markdown.
- **Human aid:** keep a slim “API handbook” (conventions, auth, pagination, error format, links to live docs).
- **Automation:** regenerate and commit the schema; catch drift in CI.
- **AI/codegen ready:** expose a stable schema URL and a committed export for tooling.

Backend setup (Django/DRF)
--------------------------
- Dependencies: `drf-spectacular` (+ `drf-spectacular-sidecar` for bundled Swagger/Redoc assets).
- Settings:
  - `INSTALLED_APPS`: add `drf_spectacular`, `drf_spectacular_sidecar`.
  - `REST_FRAMEWORK["DEFAULT_SCHEMA_CLASS"] = "drf_spectacular.openapi.AutoSchema"`.
  - `SPECTACULAR_SETTINGS`: set `TITLE`, `DESCRIPTION`, `VERSION`; allow public serving if desired via `SERVE_PERMISSIONS`.
- Routes (current project):
  - `/api/schema/` → OpenAPI JSON (`SpectacularAPIView`).
  - `/api/docs` → Swagger UI (`SpectacularSwaggerView`).
  - `/api/docs/redoc` → Redoc (`SpectacularRedocView`).
- View annotations:
  - Use serializers on responses; add `@extend_schema` / `@extend_schema_view` for custom actions.
  - Specify query/body params with `OpenApiParameter`; document error responses.
  - For viewsets without a default queryset, set `queryset = Model.objects.none()` so schema generation knows the model/id type.

Schema regeneration (AI-friendly)
---------------------------------
- From repo root: `python backend/manage.py spectacular --file backend/docs/api-schema.yaml`
- Commit the exported `backend/docs/api-schema.yaml` so AI/codegen and frontend can pin to versions.
- Optional: version the schema (`SPECTACULAR_SETTINGS["VERSION"]`) in sync with releases.

CI guardrails
-------------
- Add a CI step to regenerate the schema and fail on diffs (prevents drift).
- If schema serving requires auth, run the generation step with credentials or use the offline export above.

Pre-release/CI check script
---------------------------
- Script: `scripts/check_schema.sh`
  - Runs `python backend/manage.py spectacular --file backend/docs/api-schema.yaml`.
  - Fails if `backend/docs/api-schema.yaml` differs from the committed version (`git diff --exit-code`).
- Use in pipelines: `bash scripts/check_schema.sh` (requires Python deps installed and Django env vars set).
- Release checklist item: run the script before releasing; commit the updated schema if it changes.

GitHub Actions example (add to `.github/workflows/schema-check.yml`)
--------------------------------------------------------------------
```
name: OpenAPI schema check

on:
  pull_request:
  push:
    branches: [master, main]

jobs:
  schema:
    runs-on: ubuntu-latest
    env:
      DJANGO_ENV: development
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: pip install -r backend/requirements.txt

      - name: Verify OpenAPI schema is up to date
        run: bash scripts/check_schema.sh
```

Frontend/AI consumption
-----------------------
- Fetch the schema from `/api/schema/` (ensure CORS allows the frontend origin) or read the committed `backend/docs/api-schema.yaml`.
- Generate types/clients with tools like `openapi-typescript`, `openapi-fetch`, `orval`, `swagger-typescript-api`, or `openapi-generator`.
- Keep the schema URL stable; bump version when contracts change.

When Markdown is acceptable
---------------------------
- Only for a concise handbook: auth model, pagination pattern, error envelope, versioning policy, links to `/api/docs`, `/api/docs/redoc`, and `/api/schema/`.
- Do not mirror every endpoint/field in Markdown; rely on the generated OpenAPI instead.

Security & access
-----------------
- Decide whether `/api/docs` and `/api/docs/redoc` are public; set `SERVE_PERMISSIONS` accordingly.
- If restricted, ensure developers/CI can still export the schema via manage.py.