Skip to content

[OpenAPI] Publish availability.since in more contexts #4386

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lcawl opened this issue May 20, 2025 · 0 comments
Open

[OpenAPI] Publish availability.since in more contexts #4386

lcawl opened this issue May 20, 2025 · 0 comments

Comments

@lcawl
Copy link
Contributor

lcawl commented May 20, 2025

🚀 Feature Proposal

Currently we support the @availability property as specified in https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md, including the since detail. However, we only output the since detail in the OpenAPI document when stability is stable.

Related to elastic/kibana#221056 I think we should reconsider including that since detail in more contexts. For example, as stated in that Kibana issue:

  • if stability = stable, since should be mandatory and x-state should be "Generally available; added in xxx" where xxxx is the since value.
  • if stablility = experimental and since exists, x-state should be "Technical preview; added in xxxx` (or "Technical preview since xxx"). Otherwise it can just be "Technical preview".
  • if stability = beta and since exists, x-state should be "Beta; added xxxx" (or "Beta since xxx"). Otherwise it can continue to just be "Beta".

I think ideally since would be required in most scenarios. IMO since is not necessary in the Serverless-specific OpenAPI document, where only "Generally available", "Technical preview", and "Beta" are necessary (unless there is a need to start displaying date values in those cases). The exact terms for these lifecycle states should align with what is used in the narrative documentation frontmatter.

Motivation

This helps clarify situations where users are looking at the "main" branch of the documentation and can't tell when a new API was introduced (irrespective of its lifecycle state). The same can also occur once we have both 9.1.x and 9.0.x publishing on the "v9" branch of the documentation.

Example

For example, GetQueryRequest.ts has the following specification:

 * @availability stack since=9.1.0 stability=experimental visibility=public
 * @availability serverless stability=experimental visibility=public

Currently that appears in both OpenAPI documents as follows:

        "x-state": "Technical preview"

However, the proposed change would mean that the elasticsearch-serverless-openapi.json is unchanged but the elasticsearch-openapi.json should instead have:

  "x-state": "Technical preview; added in 9.1.0"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant