Skip to content

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

Open
@lcawl

Description

@lcawl

🚀 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"

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions