[1sakshm]

Description

Syncs contracts/ with the endpoints the app actually serves, as asked in #746, and adds a test so they can't drift apart again.

Added contracts for 15 endpoints that had none:

• forms: GET /forms/models, POST /forms/transcribe, GET /forms/submissions, GET /forms/submissions/analytics, POST /forms/purge, DELETE /forms/{submission_id}
• templates: POST /templates/upload, GET /templates/preview, POST /templates/create, POST /templates/make-fillable, DELETE /templates/{template_id}
• profiles (new path/profiles.yaml + schemas/profile.yaml): GET/POST /profiles/, GET/PATCH /profiles/{profile_id}

Removed contracts for 4 endpoints that don't exist: POST /templates, GET /templates/{template_id}, GET /templates/{template_id}/fields, POST /templates/pdf.

Updated existing contracts to match the code:

• templates.yaml / schemas/template.yaml described the original proposed design (form_type, display_name, NERIS examples, field layouts). They now describe what the routes take and return (name, description, pdf_path, fields, field_count), including PUT /templates/{id} as a partial update.
• FormFillRequest: input_id is optional and input_text is documented; FormFillResponse.values and AsyncFormFillResponse.error added; POST /forms/jobs documents its 503 and 207 responses.
• weather.yaml / zipcode.yaml: the 422 / 502 / 504 responses and error codes from Validate weather forecast query parameters #732, Return proper status codes from the address lookup endpoint #741 and Return 502 when Open-Meteo fails in the weather forecast endpoint #743.
• jobs.yaml: the 404 example now shows what the route returns (NOT_FOUND, "Job not found").
• openapi.yaml: server port 8080 → 8000 (the port compose and the Dockerfile use), a profiles tag, and X-API-Key / Bearer security schemes for the routes guarded by verify_api_key.
• common.yaml: HTTPErrorDetail (the {"detail": ...} body some template/profile routes return via HTTPException) and StatusMessage.

New tests/test_contracts.py:

• every endpoint under /api/v1 in app.openapi() has a contract
• every contract matches an endpoint that still exists
• every $ref in contracts/ resolves

On development the first two fail, listing exactly the 15 missing and 4 stale endpoints above. Uses PyYAML, which is already installed through requirements.txt.

Note: the profiles router is also mounted a second time without the /api/v1 prefix (api_router.include_router(profiles.router) in app/api/router.py, left over from 9437c60), so /profiles/ and /profiles/{profile_id} are served twice. The frontend only calls /api/v1/profiles/. I left that out of this docs PR; happy to remove the duplicate mount in a follow-up if you'd like.

Fixes #746

Type of change

• This change requires a documentation update

How Has This Been Tested?

• openapi-spec-validator on contracts/openapi.yaml (all files, refs resolved): valid
• New tests/test_contracts.py: 3 passed (2 of them fail on development)
• Full suite: python -m pytest tests/ → 413 passed
• ruff check app/ → all checks passed

Test Configuration:

• Python version: 3.11
• Docker/Compose version: N/A (tests run locally)
• OS: Windows 11

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules
• The Lint workflow check passes on this PR ✅
• The Tests workflow check passes on this PR ✅