Support a discontinued or remove-by indicator

[lcawl]

🚀 Feature Proposal

Relates to elastic/kibana#192292

Motivation

In circumstances where we know the date or version at which a "deprecated" item will move to "discontinued", that information is useful to communicate to users in advance.

Example

For example, the information could be added to the specification then output in the OpenAPI document as follows:

"components": {
  "parameters": {
      "scroll#scroll_id": {
        "in": "path",
        "name": "scroll_id",
        "description": "The scroll ID",
        "required": true,
        "deprecated": true,
        "x-discontinued": 9.0.0,
        "schema": {
          "$ref": "#/components/schemas/_types:ScrollId"
        },
        "style": "simple"
      },

[TinaHeiligers]

Kibana will be using x-state to indicate API stability and will not need to support the custom x-discontinued property.
@lcawl I'm going to close this issue as not needed. Feel free to reopen if needed in the future.