defiQUG
a2dc194a49
- Add Gitea Actions workflow; point README to gitea.d-bis.org/Sankofa_Phoenix/SMOA - Expand .gitignore for Spring H2 data, secrets, Kotlin .kotlin/, tooling - Track docs/api/generated ReDoc bundle; refresh api docs README - Android: network/auth/sync, UI shell, tests; backend credentials/integrity APIs - Docs, scripts (generate-api-docs), modules and core updates Made-with: Cursor
23 lines
905 B
Markdown
23 lines
905 B
Markdown
# 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).
|