[Lens] Improve Visualizations API documentation

oas_docs/examples/create_datatable_visualization_request.yaml

@@ -0,0 +1,27 @@
+summary: Create a data table visualization
+description: >
+  Creates a data table showing top client IPs by request count. Uses the Kibana sample web logs dataset (`kibana_sample_data_logs`).
+value:
+  type: data_table
+  title: Top client IPs by request count
+  filters: []
+  query:
+    query: ''
+  data_source:
+    type: data_view_spec
+    index_pattern: kibana_sample_data_logs
+    time_field: timestamp
+  density:
+    mode: default
+  metrics:
+    - operation: count
+      format:
+        type: number
+        decimals: 0
+      filter:
+        expression: ''
+  rows:
+    - operation: terms
+      fields:
+        - clientip
+      limit: 20

oas_docs/examples/create_datatable_visualization_response.yaml

@@ -0,0 +1,34 @@
+summary: Data table visualization response
+description: >
+  The response includes the assigned visualization ID, the full data table
+  configuration, and creation metadata.
+value:
+  id: 7c9e6030-b3c5-11ef-bd7a-2b6b1a8c0f3d
+  data:
+    type: data_table
+    title: Top client IPs by request count
+    filters: []
+    query:
+      query: ''
+    data_source:
+      type: data_view_spec
+      index_pattern: kibana_sample_data_logs
+      time_field: timestamp
+    density:
+      mode: default
+    metrics:
+      - operation: count
+        format:
+          type: number
+          decimals: 0
+        filter:
+          expression: ''
+    rows:
+      - operation: terms
+        fields:
+          - clientip
+        limit: 20
+  meta:
+    type: lens
+    created_at: '2025-03-20T10:45:00.000Z'
+    updated_at: '2025-03-20T10:45:00.000Z'

oas_docs/examples/create_metric_visualization_request.yaml

@@ -0,0 +1,30 @@
+summary: Create a metric visualization
+description: >
+  Creates a metric chart that displays the average bytes. Uses the Kibana sample web logs dataset (`kibana_sample_data_logs`).
+value:
+  type: metric
+  title: Average response time
+  data_source:
+    type: data_view_spec
+    index_pattern: kibana_sample_data_logs
+    time_field: timestamp
+  filters: []
+  query:
+    query: ''
+    language: kuery
+  metrics:
+    - type: primary
+      operation: average
+      field: bytes
+      format:
+        type: number
+        decimals: 0
+        compact: true
+      filter:
+        expression: ''
+      labels:
+        alignment: left
+      value:
+        alignment: right
+      icon:
+        name: empty

oas_docs/examples/create_metric_visualization_response.yaml

@@ -0,0 +1,37 @@
+summary: Metric visualization response
+description: >
+  The response includes the visualization ID, the full chart configuration in the data field,
+  and metadata about creation time and type.
+value:
+  id: 1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d
+  data:
+    type: metric
+    title: Average response time
+    data_source:
+      type: data_view_spec
+      index_pattern: kibana_sample_data_logs
+      time_field: timestamp
+    filters: []
+    query:
+      query: ''
+      language: kuery
+    metrics:
+      - type: primary
+        operation: average
+        field: bytes
+        format:
+          type: number
+          decimals: 0
+          compact: true
+        filter:
+          expression: ''
+        labels:
+          alignment: left
+        value:
+          alignment: right
+        icon:
+          name: empty
+  meta:
+    type: lens
+    created_at: '2025-03-20T10:30:00.000Z'
+    updated_at: '2025-03-20T10:30:00.000Z'

oas_docs/examples/create_pie_visualization_request.yaml

@@ -0,0 +1,37 @@
+summary: Create a donut chart visualization
+description: >
+  Creates a donut chart showing web traffic distribution by operating system. Uses the Kibana sample web logs dataset (`kibana_sample_data_logs`).
+value:
+  type: pie
+  title: Traffic by operating system
+  donut_hole: m
+  filters: []
+  data_source:
+    type: data_view_spec
+    index_pattern: kibana_sample_data_logs
+    time_field: timestamp
+  query:
+    query: ''
+    language: kuery
+  legend:
+    visibility: auto
+    size: auto
+  values:
+    mode: percentage
+    percent_decimals: 1
+  metrics:
+    - operation: count
+      format:
+        type: number
+        decimals: 0
+      filter:
+        expression: ''
+  group_by:
+    - operation: terms
+      fields:
+        - machine.os.keyword
+      limit: 5
+      color:
+        mode: categorical
+        palette: default
+        mapping: []

oas_docs/examples/create_pie_visualization_response.yaml

@@ -0,0 +1,44 @@
+summary: Donut chart visualization response
+description: >
+  The response includes the assigned visualization ID, the full pie/donut chart configuration,
+  and creation metadata.
+value:
+  id: 5b8d4f20-b3c5-11ef-bd7a-2b6b1a8c0f3d
+  data:
+    type: pie
+    title: Traffic by operating system
+    donut_hole: medium
+    filters: []
+    data_source:
+      type: data_view_spec
+      index_pattern: kibana_sample_data_logs
+      time_field: timestamp
+    query:
+      query: ''
+      language: kuery
+    legend:
+      visible: auto
+      size: auto
+    value_display:
+      mode: percentage
+      percent_decimals: 1
+    metrics:
+      - operation: count
+        format:
+          type: number
+          decimals: 0
+        filter:
+          expression: ''
+    group_by:
+      - operation: terms
+        fields:
+          - machine.os.keyword
+        limit: 5
+        color:
+          mode: categorical
+          palette: default
+          mapping: []
+  meta:
+    type: lens
+    created_at: '2025-03-20T10:40:00.000Z'
+    updated_at: '2025-03-20T10:40:00.000Z'

oas_docs/examples/create_xy_visualization_request.yaml

@@ -0,0 +1,52 @@
+summary: Create a line chart visualization
+description: >
+  Creates a line chart showing log entry counts over time, broken down by response code. Uses the Kibana sample web logs dataset (`kibana_sample_data_logs`).
+value:
+  type: xy
+  title: Log entries over time by response code
+  filters: []
+  query:
+    query: ''
+    language: kuery
+  legend:
+    visibility: auto
+    inside: false
+    position: right
+  fitting:
+    type: none
+  axis:
+    x:
+      title:
+        visible: true
+        value: Timestamp
+    left:
+      title:
+        visible: true
+        value: Count
+      scale: linear
+  decorations: {}
+  layers:
+    - type: line
+      data_source:
+        type: data_view_spec
+        index_pattern: kibana_sample_data_logs
+        time_field: timestamp
+      x:
+        operation: date_histogram
+        field: timestamp
+      y:
+        - operation: count
+          format:
+            type: number
+            decimals: 0
+          filter:
+            expression: ''
+      breakdown_by:
+        operation: terms
+        fields:
+          - response.keyword
+        limit: 5
+        color:
+          mode: categorical
+          palette: default
+          mapping: []

oas_docs/examples/create_xy_visualization_response.yaml

@@ -0,0 +1,59 @@
+summary: Line chart visualization response
+description: >
+  The response includes the assigned visualization ID, the full XY chart configuration,
+  and creation metadata.
+value:
+  id: 3a7c2e10-b3c5-11ef-bd7a-2b6b1a8c0f3d
+  data:
+    type: xy
+    title: Log entries over time by response code
+    filters: []
+    query:
+      query: ''
+      language: kuery
+    legend:
+      visibility: auto
+      inside: false
+      position: right
+    fitting:
+      type: none
+    axis:
+      x:
+        title:
+          visible: true
+          value: Timestamp
+      left:
+        title:
+          visible: true
+          value: Count
+        scale: linear
+    decorations: {}
+    layers:
+      - type: line
+        data_source:
+          type: data_view_spec
+          index_pattern: kibana_sample_data_logs
+          time_field: timestamp
+        x:
+          operation: date_histogram
+          field: timestamp
+        y:
+          - operation: count
+            format:
+              type: number
+              decimals: 0
+            filter:
+              expression: ''
+        breakdown_by:
+          operation: terms
+          fields:
+            - response.keyword
+          limit: 5
+          color:
+            mode: categorical
+            palette: default
+            mapping: []
+  meta:
+    type: lens
+    created_at: '2025-03-20T10:35:00.000Z'
+    updated_at: '2025-03-20T10:35:00.000Z'

oas_docs/examples/get_visualization_response.yaml

@@ -0,0 +1,37 @@
+summary: Get a metric visualization
+description: >
+  Response from retrieving a single visualization by ID. The response envelope contains
+  the visualization ID, the full chart configuration in the data field, and metadata.
+value:
+  id: 1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d
+  data:
+    type: metric
+    title: Average response time
+    data_source:
+      type: data_view_spec
+      index_pattern: kibana_sample_data_logs
+      time_field: timestamp
+    filters: []
+    query:
+      query: ''
+      language: kuery
+    metrics:
+      - type: primary
+        operation: average
+        field: bytes
+        format:
+          type: number
+          decimals: 0
+          compact: true
+        filter:
+          expression: ''
+        labels:
+          alignment: left
+        value:
+          alignment: right
+        icon:
+          name: empty
+  meta:
+    type: lens
+    created_at: '2025-03-20T10:30:00.000Z'
+    updated_at: '2025-03-20T11:15:00.000Z'