priority: high
effort: low?

🚀 Feature Proposal

Some specifications include @availability details at the API, parameter, and property level. However only the operation-level information is currently included in the OpenAPI documents. The generator should be updated to put that information into the x-state at all levels.

Motivation

Since we are currently publishing only the "current" release of the API docs for each major version, it's useful to show as much info as possible about when parameters and properties were added/deprecated/discontinued etc.

I did a quick test to verify that if the x-state information exists at the parameter level, it will be displayed in Bump.sh:

Example

For example in
https://github.com/elastic/elasticsearch-specification/blob/main/specification/_global/field_caps/FieldCapabilitiesRequest.ts
it has @availability details at the operation-level:

...
 * @rest_spec_name field_caps
 * @availability stack since=5.4.0 stability=stable
 * @availability serverless stability=stable visibility=public
...

... as well as at the parameter level:

...
    /**
     * A comma-separated list of filters to apply to the response.
     * @availability stack since=8.2.0
     * @availability serverless
     */
    filters?: string

In the generated OpenAPI files the details appear at the operation-level:

    "/_field_caps": {
      "get": {
...
        "x-state": "Added in 5.4.0"
      },

... but are missing from the parameter level:

      "field_caps-filters": {
        "in": "query",
        "name": "filters",
        "description": "A comma-separated list of filters to apply to the response.",
        "deprecated": false,
        "schema": {
          "type": "string"
        },
        "style": "form"
      },