Generate OpenAPI spec at GET /openapi.json

[daniel-sarosi-gwc]

Goal

Serve a machine-readable OpenAPI 3.1 document describing the current API surface.

This is the largest of the demo issues — it touches dependencies, multiple files, and document generation. It exercises Blitzlog's ability to plan and execute non-trivial work.

Approach

Recommended: hand-write the OpenAPI document. This keeps dependencies minimal and the spec data lives next to the code.

Alternative: use utoipa for procedural generation (more dependencies, more build time, less control).

Acceptance criteria

• GET /openapi.json returns 200 OK with Content-Type: application/json.
• The document is valid OpenAPI 3.1.
• All current endpoints are documented with request/response schemas.
• An integration test fetches /openapi.json and asserts it parses as JSON and contains the expected paths keys.

Branch

feat/issue-4-add-openapi-spec

Files to touch

• Cargo.toml — only if you chose the utoipa path.
• src/openapi.rs (new) — the spec builder.
• src/lib.rs — pub mod openapi;.
• src/bin/taskforge.rs — wire up .route("/openapi.json", get(handlers::openapi_spec)).
• src/handlers.rs — add openapi_spec handler.
• tests/integration.rs — integration test for /openapi.json.

Suggested commit shape (hand-written path)

• feat: hand-write OpenAPI 3.1 document at /openapi.json
• test: integration test for /openapi.json

Verification

• cargo test — all tests pass.
• cargo fmt --check && cargo clippy --all-targets -- -D warnings — clean.
• (Optional) npx swagger-cli validate http://localhost:3000/openapi.json — passes.

See docs/issues/04-add-openapi-spec.md for the full spec.