# 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.

## Optional CI drift check

1. Start the backend locally: `./gradlew :backend:bootRun` (or run the JAR).
2. Export: `curl -s http://localhost:8080/v3/api-docs -o /tmp/smoa-openapi.json`
3. Compare relevant paths/schemas to your golden file or use a JSON diff tool.

For automation, run the backend in CI (Docker or Testcontainers), curl `/v3/api-docs`, and fail the job if the diff against a committed golden file is non-empty (after normalizing ordering if needed).

## Script

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