feat: keep the API and its OpenAPI document in sync continuously

[darwin67]

Summary

Stacked on #78. In #78 the spec is a hand-written file away from the code, and only one test file checks responses, so drift goes unnoticed until someone looks. This PR makes the spec part of the code and enforces it on every request and in every test. No backwards compatibility is kept, since the API is pre-1.0.

1. The spec lives next to each action (refactor ×2)

• Each controller action declares its operation with OpenApiSpex.ControllerSpecs, directly above the function.
• TextbinWeb.ApiSpec assembles the document from the router.
• TextbinWeb.ApiDocs holds the shared pieces: responses, UUID path parameters, and the paste query fields.
• Workspace-scoped paste routes now have their own workspace_* actions. open_api_spex looks operations up by action, and only the workspace routes have a workspace_id. in_workspace/1 derives each workspace variant from its personal spec, so the personal and workspace operations can't diverge.
• A test fails if any API action has no operation. Without it, such a route would silently drop out of the document.

2. Requests must match the spec (feat!)

• TextbinWeb.ApiRequestValidation validates path parameters, query parameters and JSON bodies against the action's operation.
• Anything else gets a 422 in the existing ValidationError shape: {"errors": {"field": ["message"]}}.
• Request schemas are closed, and an operation with no query parameters accepts none.
• Raw paste uploads keep any content type, since it's stored with the paste. open_api_spex only matches bodies by exact type, so these skip body validation, but their query parameters are still checked.
• Breaking changes:
  • Bodies must be JSON.
  • {"paste": {...}} and bare JSON strings are rejected; send {"data": ...}.
  • A malformed UUID is now a 422, not a 400 (or a 204 for delete).
  • POST /auth/tokens returns a 422 for a missing email or password, or a non-string name.

3. Every API response in every test is checked (test)

• TextbinWeb.ApiResponseCheck sits in the :api pipeline and hands each response to a checker. It's switched on only in config/test.exs, at compile time, so production is unaffected.
• The checker fails the test unless the status is documented and the body matches its schema. Every existing API test is therefore a contract test with no edits.
• After a full mix test, the suite fails if any documented response was never produced, so stale statuses can't linger. Partial runs skip this check.
• ApiContractTest now covers what every operation shares, across all of them:
  • a 401 with no token;
  • a 422 for an undeclared query parameter;
  • each documented 404 for unknown IDs;
  • purge's 503 when storage can't delete.

4. Spec corrections found by the coverage check (fix)

• "Workspace not found" (404) is no longer listed on personal-workspace operations; that workspace always exists.
• deletePaste's 503 is removed. Delete no longer touches storage since the soft-delete lifecycle, so it can't fail there.

Drift caught on purpose

Change	Result
Extra surprise field in PasteJSON	23 paste tests fail: createPasteInWorkspace 201 response does not match its operation: Unexpected field: surprise
410 instead of 404 for a missing paste	Fails with getPasteInWorkspace returned 410, which its operation does not document (documented: [200, 401, 404, 422])
A documented 409 nothing sends	The full run exits 1 and lists getPaste 409
Undocumented query parameter or legacy body	422, e.g. {"errors":{"bogus":["Unexpected field: bogus"]}}

When you change the API

Edit the operation above the action, run mix openapi.export, and commit priv/openapi.json. If anything is missed, the tests fail. AGENTS.md says the same.

Test plan

• mix test: 577 tests, 0 failures. The full run passes the coverage check.
• mix credo reports no issues. mix compile --warnings-as-errors is clean.
• I ran the CLI end to end against a validating local server: whoami, create with a title and reference, show, delete, deleted, restore, and permanent delete all pass. A bad ID and unknown parameters return readable field errors.
• The deliberate breakages in the table above are each caught.

🤖 Generated with Claude Code

https://claude.ai/code/session_019fnjMN7WpEjQJD2zveakV6

---

Generated by Claude Code

[darwin67]

Oracle review complete: signed off after resolving three request-boundary blockers. Reject _json wrappers so validation and controller consumption cannot see different objects; reject undeclared JSON/raw bodies on bodyless operations; derive scope/deletion dispatch only from route path params. A first-position paste upload parser now leaves non-JSON media types unread for the existing bounded spooler, with raw metadata taken only from query params. Regressions failed before fixes (conflicting _json create accepted, auth wrapper error, body-injected workspace deletion accepted, form bytes altered). Afterward tests cover rejection/unchanged persistence, every bodyless mutation operation with JSON/raw input, and exact-byte personal/workspace uploads for URL-encoded, multipart and +json content, including invalid JSON bytes. Preserved a concurrent remote 300KB multi-chunk upload regression via a history-preserving merge; oracle signed off on that final integration too. Final validation: mix precommit (582 ExUnit tests plus JS tests), full response-status coverage and mix credo passed; mix openapi.export is unchanged. Corrections committed and pushed without rewriting published history. No route authentication changes, merge to base, or deployment. Review session: https://ampcode.com/threads/T-01a12594-e2f1-75be-b343-9239564f5c84

Post-push CI is green at the final reviewed head: memory/local/S3 Elixir test matrix, Rust tests, formatting/linting, and production-container build passed. Release/publication jobs skipped as expected.