nevzheng opened a new pull request, #11986:
URL: https://github.com/apache/gravitino/pull/11986
### What changes were proposed in this pull request?
Adds a dedicated, Dependabot-tracked OpenAPI quality-gate for
`docs/open-api`, replacing the Gradle-embedded lint.
- **New workflow** `.github/workflows/openapi.yml` — five independent (fully
parallel) jobs, all **warn-only**:
- `redocly-lint` — structural validation as a matrix over `minimal` /
`recommended` / `recommended-strict`
- `spectral-lint` — governance kitchen sink (OWASP + documentation +
Gravitino house rules); a linter **crash is surfaced as an investigate-the-spec
signal**, never silenced
- `bundle` — resolves the ~30 files into a single `openapi.json`/`.yaml`,
uploaded as the `gravitino-openapi-spec` artifact
- `codegen` — progenitor (Rust) codegen smoke test
- `breaking-changes` — `oasdiff` vs the PR base branch
- **New tooling dir** `dev/openapi/` — `package.json` (pinned `@redocly/cli`
2.x, `@stoplight/spectral-cli`, OWASP + documentation rulesets) + lockfile,
`redocly.yaml`, `.spectral.yaml` (four `gravitino-*` house rules), `README.md`.
- **Dependency tracking** — `.github/dependabot.yml` now watches
`dev/openapi` (npm); the existing `github-actions` entry already covers the
workflow's action pins.
- **Removes** the OpenAPI lint from Gradle — deletes `docs/build.gradle.kts`
(`:docs` still configures via the root `subprojects` block; `./gradlew
:docs:help` → exit 0).
- **New docs page** `docs/openapi-validation-and-publishing.md` and updated
`AGENTS.md` validation note.
### Why are the changes needed?
The OpenAPI description is the contract downstream, non-Java consumers rely
on — SDK generators, connectors, mock servers. Keeping it strictly valid and
codegen-clean is what makes the polyglot ecosystem cheap to grow. This makes
validation a first-class, always-current workflow, produces a single
machine-readable artifact for generators, and enforces house conventions
mechanically. It lands **expose-first (warn-only)**: it deliberately does
**not** modify spec content, so the existing findings surface as annotations
without blocking, and rules graduate to enforcing as the backlog is addressed.
Fix: #11985
### Does this PR introduce _any_ user-facing change?
- New docs page: *OpenAPI validation and publishing*.
- New CI artifact `gravitino-openapi-spec` (bundled `openapi.json`/`.yaml`)
on every relevant run.
- Local OpenAPI validation moves from `./gradlew :docs:build` to `cd
dev/openapi && npm run lint` (noted in `AGENTS.md`).
- No REST API, schema, or property-key changes.
### How was this patch tested?
Ran the runnable stages locally against the spec:
- Redocly matrix — gradient confirmed: `minimal` 4 warnings → `recommended`
9 → `recommended-strict` 10 errors.
- Spectral — crash reproduced (exit 2, zero report) and confirmed
doc-specific (the clean idp spec lints through to 76 findings); crash-detection
logic verified.
- `redocly bundle` — produces valid single-file `openapi.json` (~484 KB).
- `./gradlew :docs:help` — exit 0 after deleting `docs/build.gradle.kts`.
- Workflow + `dependabot.yml` YAML validated.
- `codegen` (progenitor) and `breaking-changes` (oasdiff) run in CI only
(Rust/Docker); both warn-only.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
