[Improvement] Publish the bundled OpenAPI specification as a versioned artifact
- Dominant language
- Java
- Stars
- 3.2k
- Forks
- 935
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 339
Description
### What would you like to be improved?
Gravitino owns the OpenAPI source under `docs/open-api/`, but downstream consumers do not have a stable, versioned artifact containing the bundled specification.
The OpenAPI workflow proposed in #11986 creates `openapi.yaml` and `openapi.json` and uploads them as a workflow-run artifact. However, the documentation site needs a release-oriented artifact that it can retrieve deterministically. Re-bundling or copying the source files in `gravitino-site` could allow the rendered reference and published raw specification to drift.
This is needed by:
- https://github.com/apache/gravitino-site/issues/138
- https://github.com/apache/gravitino/issues/11985
- https://github.com/apache/gravitino/pull/11986
### How should we improve?
Provide one supported CLI/build entry point that bundles `docs/open-api/openapi.yaml` into self-contained YAML and JSON files. This could be a Gradle task such as:
./gradlew :docs:bundleOpenApi
or a documented equivalent backed by `dev/openapi`.
Publish the resulting bundle from the build/release workflow using an explicit, versioned artifact name and a location that another repository can retrieve reliably.
Acceptance criteria:
- A documented command produces self-contained `openapi.yaml` and `openapi.json`.
- The build/release workflow publishes those files as a clearly named, versioned artifact.
- The artifact can be retrieved by an exact Gravitino release or documentation version.
- The published files are generated from the same commit used for the release.
- CI validates the bundle before publication.
- `gravitino-site` can consume the artifact for its Docusaurus OpenAPI reference and raw-spec link without re-bundling it.
Contributor guide
Research direction
Start with docs/open-api/openapi.yaml, the workflow proposed in #11986, and the suggested :docs:bundleOpenApi task or dev/openapi entry point. Confirm that CI validates self-contained YAML and JSON bundles and that the release workflow publishes a versioned artifact from the release commit, retrievable by gravitino-site without re-bundling.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, openapi
- Domain
- api, build-system, ci-cd, release
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100