# Keeping OpenAPI in sync

## Source of truth

The **running Spring Boot app** exposes the authoritative contract:

- **OpenAPI JSON:** `GET /v3/api-docs`
- **Swagger UI:** `/swagger-ui.html`

The static file `docs/api/api-specification.yaml` is a **human-maintained reference** for design reviews. It can drift from springdoc.

## CI drift check (implemented baseline)

`OpenApiContractIntegrationTest` (module `:backend`) loads the Spring context and asserts that `/v3/api-docs` includes expected paths (e.g. `/api/v1/sync/credential`, `/api/v1/credentials`, `/api/v1/directory`, `/api/v1/integrity/verify`). It runs as part of `./gradlew :backend:test` and therefore **`./gradlew smoaVerify`**.

For a **full golden-file diff**, still optional: start the backend, `curl` `/v3/api-docs`, and compare to a committed artifact (normalize JSON ordering if needed).

## Script

See `scripts/export-openapi-local.sh` for a minimal local export (requires a reachable backend).