Add OpenAPI documentation endpoint and schema

[ragnorc]

Summary

This PR adds comprehensive OpenAPI 3.1 documentation support to the Omnigraph server, including a new /openapi.json endpoint and extensive test coverage for the API specification.

Key Changes

• OpenAPI Endpoint: Added /openapi.json GET endpoint that serves the OpenAPI specification without requiring authentication
• API Documentation: Decorated all server endpoints with #[utoipa::path] macros to automatically generate OpenAPI documentation including:
  • Request/response schemas with proper references
  • HTTP methods and status codes
  • Path and query parameters
  • Security requirements (bearer token authentication)
  • Operation tags for logical grouping
• Schema Documentation: Added ToSchema derives to all API request/response types in api.rs to enable automatic schema generation
• Security Configuration: Implemented SecurityAddon modifier to register bearer token security scheme in the OpenAPI spec
• Comprehensive Test Suite: Added 844-line test file (openapi.rs) with 60+ tests covering:
  • Endpoint availability and HTTP methods
  • Schema presence and field validation
  • Enum variants for LoadMode, BranchMergeOutcome, ErrorCode, and MergeConflictKindOutput
  • Security requirements on protected endpoints
  • Path and query parameters
  • Request/response body schema references
  • Round-trip serialization and endpoint consistency

Implementation Details

• The ApiDoc struct uses the #[openapi] macro to aggregate all endpoint documentation
• All protected endpoints (except /healthz) require bearer token authentication in the spec
• The /openapi.json endpoint is intentionally unprotected to allow API discovery
• Tests validate both static spec generation and live endpoint behavior
• Added utoipa dependency to workspace with required features for OpenAPI 3.1 support

https://claude.ai/code/session_01NfoPVx21rZUQned1f7WpXY

---

Note

Medium Risk
Adds a new public /openapi.json route and introduces OpenAPI annotations across all HTTP handlers; while mostly additive, it touches server routing and security-documentation behavior (including conditional stripping of security metadata) which could affect API discovery or auth expectations.

Overview
Adds OpenAPI 3.1 documentation generation to omnigraph-server using utoipa, including a new unauthenticated GET /openapi.json endpoint that serves the generated spec.

All existing API handlers are annotated with #[utoipa::path] and request/response types in api.rs now derive ToSchema/IntoParams (with a documented shadow schema for LoadMode), and the spec registers a bearer-token security scheme that is stripped from the served spec when the server is running without auth.

Introduces an extensive tests/openapi.rs suite validating path/method coverage, schema shapes/enums, security requirements, and that the served spec matches static generation (and differs appropriately in open-mode).

^{Reviewed by Cursor Bugbot for commit 4c07d3c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dfa92855f6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Make endpoint security requirements match runtime auth mode

The OpenAPI operation annotations hard-code security(("bearer_token" = [])) for protected routes, but the middleware only enforces bearer auth when AppState::requires_bearer_auth() is true. In deployments started without configured tokens (the default open path), these endpoints are actually callable anonymously while the spec says auth is mandatory, which can break generated clients or automation that treat the token as required. Consider emitting security requirements conditionally (or documenting both modes) so the spec reflects actual server behavior.

Useful? React with 👍 / 👎.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit dfa9285. Configure here.}

[aaltshuler]

The OpenAPI annotations currently declare bearer auth as required on the protected routes, but runtime auth is still conditional: require_bearer_auth only enforces a token when AppState::requires_bearer_auth() is true. In the default open deployment with no configured bearer tokens or policy, /snapshot, /read, /change, /export, /branches, /runs, and /commits remain anonymously callable while the generated spec says auth is mandatory.

That makes the OpenAPI document inaccurate for generated clients and any automation that treats the spec as authoritative. Please resolve that mismatch before merge by either:

• making auth unconditional for those routes, or
• adjusting the generated/documented security requirements so they reflect both open and authenticated server modes.

I don’t see other blocking issues in the PR.

[aaltshuler]

The OpenAPI auth/spec mismatch is fixed on the rebased head. I do not see a remaining blocker in this PR.