Default, Version & Description Parameter Annotations

[philkra]

🚀 Feature Proposal

Enable the enrichment of request parameters via annotation with

• a default value
• version introduced
• parameter description
  All values should be optional and this must been seen as a long term goal to provide this data with collaboration of other teams.

Motivation

1. Developer experience, by getting a hint on the default value of a parameter and a proper description.
2. The docs team could provide more elaborate generated documentation.
3. The UI could add more context to UI fields and generate larger parts of forms.

Example

Example definition of a param within a request class:

/**
 * @default 30s
 * @description This is the description of a parameter that was introduced in 7.8.0 with the default value 30s
 * @version 7.8.0
 */
a_parameter: string

json output:

{
  "name": "a_parameter",
  "required": true,
  "default": "30s",
  "description": "This is the description of a parameter that was introduced in 7.8.0 with the default value 30s",
  "version": "7.8.0",
  "type": {
    "kind": "instance_of",
    "type": {
      "name": "SearchableSnapshotsUsage",
      "namespace": "x_pack.info.x_pack_usage"
    }
  }
}