Description
🚀 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 andx-state
should be "Generally available; added in xxx" where xxxx is thesince
value. - if
stablility
=experimental
andsince
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
andsince
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"