[OpenAPI] Publish availability.since in more contexts
#4386
Comments
|
There are also related discussions occurring in the context of the narrative docs ("Docs Versioning RFC") about the need to make the whole journey clear. In particular, the current proposal is that "Lifecycle statuses are additive: if a feature is beta in 9.1 and GA in 9.2, both statuses should be specified in a comma-separated list. We will simplify the output when the lifecycle tags are rendered." If that proposal moves forward, it might mean that we'll need to match that design in the Elasticsearch (and other) API specifications. For example, maybe we might need something like this: And then in the OpenAPI output, maybe this could continue to be rendered in a single string e.g. in Maybe in the longer term it would be better to put this in an object or array, for example: ... but that would require changes across all API generation tools and in our publishing site too. cc @Mpdreamz, @georgewallace, @szabosteve for longer term decision-making |
Uh oh!
There was an error while loading. Please reload this page.
🚀 Feature Proposal
Currently we support the
@availabilityproperty as specified in https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md, including thesincedetail. However, we only output thesincedetail in the OpenAPI document whenstabilityisstable.Related to elastic/kibana#221056 I think we should reconsider including that
sincedetail in more contexts. For example, as stated in that Kibana issue:stability=stable,sinceshould be mandatory andx-stateshould be "Generally available; added in xxx" where xxxx is thesincevalue.stablility=experimentalandsinceexists,x-stateshould be "Technical preview; added in xxxx` (or "Technical preview since xxx"). Otherwise it can just be "Technical preview".stability=betaandsinceexists,x-stateshould be "Beta; added xxxx" (or "Beta since xxx"). Otherwise it can continue to just be "Beta".I think ideally
sincewould be required in most scenarios. IMOsinceis 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:
Currently that appears in both OpenAPI documents as follows:
However, the proposed change would mean that the
elasticsearch-serverless-openapi.jsonis unchanged but theelasticsearch-openapi.jsonshould instead have:The text was updated successfully, but these errors were encountered: