| name | check-oas |
| description | Detect breaking changes in docs/mapi/openapi.yaml and check whether the committed spec is stale; run the OAS checks, interpret findings, and guide fixes. |
OpenAPI Spec Checks
Two independent scripts cover the management API spec at docs/mapi/openapi.yaml:
| Script | What it does | Exits |
|---|
oas-staleness-check.sh | Regenerates the spec from source and diffs against the committed file | 0 or 1 |
oas-compat-check.sh | Checks the committed spec for breaking changes since the merge-base | 0 or 1 |
oas-staleness-check.sh
Runs scripts/regen-oas.sh into a temp directory and diffs the result against the committed
docs/mapi/openapi.yaml. If they differ, a warning and diff summary are printed.
Exits 1 if the committed spec differs from the regenerated output. The regeneration is
deterministic — paths, tags, schemas, and schema properties are all explicitly sorted in
GraviteeApiDefinition.afterScan() — so any diff is a genuine mismatch. Internal refactors
and model changes that don't affect the REST layer produce no diff.
Exits 0 if the spec is up to date, or if regeneration itself fails (compilation error,
missing module). A build failure is not reported as a staleness failure.
First-run note: if the committed spec was previously generated by the running server rather
than scripts/regen-oas.sh, there may be one-time differences in formatting or endpoints.
Run bash scripts/regen-oas.sh once and commit the result to establish the canonical
plugin-generated baseline before this check is enforced.
Requires the management API module to be compiled. In CI this is satisfied by the
process_pull_request workspace. Locally, pass --also-make to compile first.
bash .circleci/scripts/oas-staleness-check.sh
bash .circleci/scripts/oas-staleness-check.sh --also-make
If the check warns that the spec is stale, regenerate and commit:
bash scripts/regen-oas.sh
bash scripts/regen-oas.sh --also-make
See Updating the spec for how regeneration works.
oas-compat-check.sh
Compares docs/mapi/openapi.yaml at the merge-base against HEAD (or the working tree when
--use-head false) using oasdiff. Exits 1 if
breaking changes are found, unless a version-boundary exemption applies.
If the spec has not changed since the merge-base, the check exits 0 immediately.
Requires oasdiff on PATH:
brew install tufin/tufin/oasdiff
OASDIFF_VERSION=$(cat .oasdiff-version)
curl -sSL "https://github.com/tufin/oasdiff/releases/download/v${OASDIFF_VERSION}/oasdiff_${OASDIFF_VERSION}_linux_amd64.tar.gz" \
| tar -xz -C /usr/local/bin oasdiff
Baseline resolution
When --base is omitted the baseline is resolved automatically
(see .circleci/scripts/_compat_common.sh):
master or x.y.x release branches → HEAD~1- All other branches → git tracking branch (
@{u}) if set to a different branch, else HEAD~1
bash .circleci/scripts/oas-compat-check.sh
bash .circleci/scripts/oas-compat-check.sh --base 4.11.0
bash .circleci/scripts/oas-compat-check.sh --base origin/master
bash .circleci/scripts/oas-compat-check.sh --base abc1234
bash .circleci/scripts/oas-compat-check.sh --base HEAD~10
bash .circleci/scripts/oas-compat-check.sh --use-head false
oasdiff breaking path/to/old-openapi.yaml docs/mapi/openapi.yaml
Breaking-change exemption
oas-compat-check.sh still runs oasdiff and prints findings, but exits 0 regardless, in two
cases detected by comparing pom.xml <version> at baseline vs. HEAD:
- Minor version bump — e.g.
4.11.x → 4.12.x. Breaking changes between minor releases
are expected.
- Patch is zero — e.g.
4.12.0. No release of this minor version exists yet, so there
are no deployed clients to protect.
What counts as a breaking change
Key categories (not exhaustive — see oasdiff breaking changes):
| Category | Example |
|---|
| Path removed | DELETE /domains/{domainId}/applications removed |
| Operation removed | GET removed from an existing path |
| Required request parameter added | New required query or path parameter |
| Required request body property added | New required field in a request schema |
| Response property removed | Field removed from a response schema |
| Response property type changed | string → integer |
| Enum value removed | "RS256" removed from allowed JWT algorithms |
| Security scheme changed | Auth requirement added or removed |
Understanding oasdiff output
☑️ Api Changes:
error [response-property-removed] at paths./api/organizations/{organizationId}/domains.get.responses.200.content.application/json
deleted property 'total' from response
warning [request-parameter-default-value-changed] at paths./api/organizations/{organizationId}/domains.get.parameters[0]
changed default value from '0' to '1' for path parameter 'page'
- error — breaking change;
oas-compat-check.sh exits 1 unless exempted
- warning — potentially breaking or informational; exits 0
How to fix breaking changes
| Error | Fix |
|---|
| Response property removed | Keep the field; mark it deprecated in description |
| Required request parameter added | Make the new parameter optional with a default |
| Required request body property added | Make it optional (remove from required) or provide a default |
| Enum value removed | Keep the old value in the enum |
| Path or operation removed | Deprecate first; remove only in a new minor version |
Updating the spec
docs/mapi/openapi.yaml can be regenerated without starting the management API server using
scripts/regen-oas.sh. It uses swagger-maven-plugin-jakarta to scan JAX-RS annotations at
build time — the GraviteeApiDefinition ReaderListener is auto-discovered and invoked,
producing the same sorted paths, tags, and security schemes as the runtime output. Two things
are patched post-generation:
info.version — the plugin reads Version.RUNTIME_VERSION (gravitee-common library
version, not the project version); patched from pom.xml via mvn help:evaluate.- License header — extracted from the committed spec before overwriting and prepended to
the generated file; required by the
license-maven-plugin validate check.
bash scripts/regen-oas.sh
bash scripts/regen-oas.sh --also-make
Alternatively, regenerate via the running server (always authoritative):
curl -s http://localhost:8093/management/openapi.yaml > docs/mapi/openapi.yaml
Commit the updated spec alongside your code changes.
