Skip to content

openapi.md

Latest commit

 

History

History
93 lines (63 loc) · 2.75 KB

openapi.md

File metadata and controls

93 lines (63 loc) · 2.75 KB

OpenAPI Contract

The committed API contract is openapi.yaml. It is generated from the HTTP adapter route registry and route-contract metadata.

Generate And Check

Generate the contract:

go run ./cmd/openapi > openapi.yaml

Check drift:

make openapi-check

make openapi-check regenerates the contract, compares it with the committed file, and runs route contract tests for the HTTP adapter. It also checks that the rendered static API docs in docs/openapi/index.html and site/marketing/public/api/index.html match the committed contract.

Check precision regression:

make openapi-precision-check

make openapi-precision-check enforces endpoint-specific contracts for all registered public routes and fails if any operation falls back to a broad request or response shape.

Render the human-readable static API docs after changing route metadata:

scripts/render_openapi_docs.py --write

Check the rendered docs without modifying files:

make rendered-openapi-check

make docs-check compares the paths in openapi.yaml with the endpoint catalog in API reference. Add every generated path to that catalog, or the docs check fails.

Review The Contract

The committed file is compact. For human review, pretty-print it without editing the generated source:

jq . openapi.yaml > /tmp/evydence-openapi.pretty.json
jq '.paths | keys[]' openapi.yaml
jq '.components.schemas | keys[]' openapi.yaml

Inspect one operation:

jq '.paths["/v1/evidence"].post' openapi.yaml

For a browser-friendly route and schema index, open:

docs/openapi/index.html

The marketing-site copy is generated at:

site/marketing/public/api/index.html

The rendered page is static, uses no remote scripts, and is regenerated from the committed public OpenAPI contract. It must not contain runtime secrets, tenant data, raw evidence payloads, bearer tokens, private keys, or customer package contents.

The API also serves the generated contract at:

GET /v1/openapi.json

Current Limitations

  • openapi.yaml is generated in a compact JSON-compatible representation.
  • docs/openapi/index.html is generated from openapi.yaml for human review.
  • Registered public routes have endpoint-specific request and response schemas.
  • New routes must update operation metadata, component schemas, openapi.yaml, the generated API contract matrix, and the rendered OpenAPI docs.
  • Do not hand-edit openapi.yaml; update route metadata or the generator, then run make openapi-check.

Route registration and OpenAPI generation use the same HTTP adapter registry so tests can catch missing routes or stale operation metadata.