apache / apache/gravitino

[Improvement] Publish the bundled OpenAPI specification as a versioned artifact

Open
#12,029 0 comments 0 reactions 0 assignees View on GitHub
improvement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.