nevzheng opened a new issue, #138: URL: https://github.com/apache/gravitino-site/issues/138
## Problem\n\nThe generated OpenAPI reference is available as rendered documentation, but the raw machine-readable specification is not published at a stable, versioned URL on the docs site.\n\nThat means downstream users cannot reliably point generators, validators, mock servers, or client tooling at the same published artifact that corresponds to a Gravitino release.\n\n## Proposal\n\nPublish the raw bundled OpenAPI specification from the Gravitino docs site at a stable, versioned URL, alongside the rendered API reference.\n\nThe implementation belongs in this repository's Docusaurus OpenAPI configuration (docusaurus-plugin-openapi-docs): expose the generated/bundled specification as a static asset and ensure its URL is version-aware and stable across releases.\n\n## Acceptance criteria\n\n- A raw OpenAPI artifact is reachable from the published docs site for each supported documentation version.\n- The URL is stable and documented (for example, a release/versioned path ending i n .yaml and/or .json).\n- The published artifact is the same bundled specification used to generate the rendered OpenAPI reference.\n- The rendered API reference links to the raw specification.\n- The build/release path prevents the rendered reference and raw artifact from drifting.\n\n## Why this matters\n\nA stable raw spec enables generated clients and integrations outside the Java ecosystem, contract validation, compatibility checks, and tooling such as mock servers or schema-guided testing. It is an adoption and API-contract concern, not only a documentation enhancement.\n\n## Related work\n\n- https://github.com/apache/gravitino/issues/11985\n- https://github.com/apache/gravitino/discussions/11999\n\n## Ownership\n\nI am happy to implement this. Could a maintainer please assign this issue to @nevzheng? -- 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]
