[Discover] Update data view API docs (#187146)

- Closes https://github.com/elastic/kibana/issues/187075 ## Summary This PR updates data view API docs. `customDescription` was added in https://github.com/elastic/kibana/pull/168577 --------- Co-authored-by: Lisa Cawley <lcawley@elastic.co> Co-authored-by: Davis McPhee <davismcphee@hotmail.com>
2025-04-23 17:28:26 -04:00 · 2024-07-11 11:33:52 +02:00 · 2024-07-11 11:33:52 +02:00 · cd4a782cac
commit cd4a782cac
parent 1f7fdfdfe4
9 changed files with 92 additions and 23 deletions
--- a/docs/api/data-views/create.asciidoc
+++ b/docs/api/data-views/create.asciidoc
@ -231,10 +231,13 @@ The API returns the {data-source} object:
 .Properties of the fieldAttrs[fieldName] objects:
 [%collapsible%open]
 =====
-`customLabel`:::
+`customLabel`::
 (Optional, string) Custom label for the field.

-`count`:::
+`customDescription`::
+(Optional, string) Custom description for the field. Max length is 300 characters.
+
+`count`::
 (Optional, number) Popularity count for the field.
 =====

--- a/docs/api/data-views/update-fields.asciidoc
+++ b/docs/api/data-views/update-fields.asciidoc
@ -5,7 +5,7 @@
 ++++

 experimental[] Update fields presentation metadata, such as `count`,
-`customLabel`, and `format`. You can update multiple fields in one request. Updates
+`customLabel`, `customDescription`, and `format`. You can update multiple fields in one request. Updates
 are merged with persisted metadata. To remove existing metadata, specify `null` as the value.


@ -119,7 +119,8 @@ $ curl -X POST api/data_views/data_view/my-view/fields
            "customLabel": "Foo"
        },
        "bar": {
-            "customLabel": "Bar"
+            "customLabel": "Bar",
+            "customDescription": "Bar Custom description"
        }
    }
 }
--- a/src/plugins/data_views/docs/openapi/bundled.json
+++ b/src/plugins/data_views/docs/openapi/bundled.json
@ -1036,7 +1036,7 @@
      "post": {
        "summary": "Update data view fields metadata in the default space",
        "operationId": "updateFieldsMetadataDefault",
-        "description": "Update fields presentation metadata such as count, customLabel and format. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. You can update multiple fields in one request. Updates are merged with persisted metadata. To remove existing metadata, specify null as the value.\n",
+        "description": "Update fields presentation metadata such as count, customLabel, customDescription, and format. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. You can update multiple fields in one request. Updates are merged with persisted metadata. To remove existing metadata, specify null as the value.\n",
        "tags": [
          "data views"
        ],
@ -2786,11 +2786,16 @@
        }
      },
      "update_field_metadata_request": {
-        "summary": "Set popularity count for field foo.",
+        "summary": "Update multiple metadata fields.",
        "value": {
          "fields": {
-            "foo": {
-              "count": 123
+            "field1": {
+              "count": 123,
+              "customLabel": "Field 1 label"
+            },
+            "field2": {
+              "customLabel": "Field 2 label",
+              "customDescription": "Field 2 description"
            }
          }
        }
@ -3465,7 +3470,22 @@
      },
      "fieldattrs": {
        "type": "object",
-        "description": "A map of field attributes by field name."
+        "description": "A map of field attributes by field name.",
+        "properties": {
+          "count": {
+            "type": "integer",
+            "description": "Popularity count for the field."
+          },
+          "customDescription": {
+            "type": "string",
+            "description": "Custom description for the field.",
+            "maxLength": 300
+          },
+          "customLabel": {
+            "type": "string",
+            "description": "Custom label for the field."
+          }
+        }
      },
      "fieldformats": {
        "type": "object",
@ -3532,7 +3552,10 @@
                "$ref": "#/components/schemas/allownoindex"
              },
              "fieldAttrs": {
-                "$ref": "#/components/schemas/fieldattrs"
+                "type": "object",
+                "additionalProperties": {
+                  "$ref": "#/components/schemas/fieldattrs"
+                }
              },
              "fieldFormats": {
                "$ref": "#/components/schemas/fieldformats"
@ -3591,7 +3614,10 @@
                "$ref": "#/components/schemas/allownoindex"
              },
              "fieldAttrs": {
-                "$ref": "#/components/schemas/fieldattrs"
+                "type": "object",
+                "additionalProperties": {
+                  "$ref": "#/components/schemas/fieldattrs"
+                }
              },
              "fieldFormats": {
                "$ref": "#/components/schemas/fieldformats"
--- a/src/plugins/data_views/docs/openapi/bundled.yaml
+++ b/src/plugins/data_views/docs/openapi/bundled.yaml
@ -646,7 +646,7 @@ paths:
      summary: Update data view fields metadata in the default space
      operationId: updateFieldsMetadataDefault
      description: |
-        Update fields presentation metadata such as count, customLabel and format. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. You can update multiple fields in one request. Updates are merged with persisted metadata. To remove existing metadata, specify null as the value.
+        Update fields presentation metadata such as count, customLabel, customDescription, and format. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. You can update multiple fields in one request. Updates are merged with persisted metadata. To remove existing metadata, specify null as the value.
      tags:
        - data views
      parameters:
@ -1966,11 +1966,15 @@ components:
        data_view_id: ff959d40-b880-11e8-a6d9-e546fe2bba5f
        force: true
    update_field_metadata_request:
-      summary: Set popularity count for field foo.
+      summary: Update multiple metadata fields.
      value:
        fields:
-          foo:
+          field1:
            count: 123
+            customLabel: Field 1 label
+          field2:
+            customLabel: Field 2 label
+            customDescription: Field 2 description
    create_runtime_field_request:
      summary: Create a runtime field.
      value:
@ -2507,6 +2511,17 @@ components:
    fieldattrs:
      type: object
      description: A map of field attributes by field name.
+      properties:
+        count:
+          type: integer
+          description: Popularity count for the field.
+        customDescription:
+          type: string
+          description: Custom description for the field.
+          maxLength: 300
+        customLabel:
+          type: string
+          description: Custom label for the field.
    fieldformats:
      type: object
      description: A map of field formats by field name.
@ -2556,7 +2571,9 @@ components:
            allowNoIndex:
              $ref: '#/components/schemas/allownoindex'
            fieldAttrs:
-              $ref: '#/components/schemas/fieldattrs'
+              type: object
+              additionalProperties:
+                $ref: '#/components/schemas/fieldattrs'
            fieldFormats:
              $ref: '#/components/schemas/fieldformats'
            fields:
@ -2596,7 +2613,9 @@ components:
            allowNoIndex:
              $ref: '#/components/schemas/allownoindex'
            fieldAttrs:
-              $ref: '#/components/schemas/fieldattrs'
+              type: object
+              additionalProperties:
+                $ref: '#/components/schemas/fieldattrs'
            fieldFormats:
              $ref: '#/components/schemas/fieldformats'
            fields:
--- a/src/plugins/data_views/docs/openapi/components/examples/update_field_metadata_request.yaml
+++ b/src/plugins/data_views/docs/openapi/components/examples/update_field_metadata_request.yaml
@ -1,9 +1,14 @@
-summary: Set popularity count for field foo.
+summary: Update metadata for multiple fields.
 value:
  {
    "fields": {
-        "foo": {
-            "count": 123
+        "field1": {
+            "count": 123,
+            "customLabel": "Field 1 label"
+        },
+        "field2": {
+            "customLabel": "Field 2 label",
+            "customDescription": "Field 2 description"
        }
    }
 }
--- a/src/plugins/data_views/docs/openapi/components/schemas/create_data_view_request_object.yaml
+++ b/src/plugins/data_views/docs/openapi/components/schemas/create_data_view_request_object.yaml
@ -12,7 +12,9 @@ properties:
      allowNoIndex:
        $ref: 'allownoindex.yaml'
      fieldAttrs:
-        $ref: 'fieldattrs.yaml'
+        type: object
+        additionalProperties:
+          $ref: 'fieldattrs.yaml'
      fieldFormats:
        $ref: 'fieldformats.yaml'
      fields:
--- a/src/plugins/data_views/docs/openapi/components/schemas/data_view_response_object.yaml
+++ b/src/plugins/data_views/docs/openapi/components/schemas/data_view_response_object.yaml
@ -7,7 +7,9 @@ properties:
      allowNoIndex:
        $ref: 'allownoindex.yaml'
      fieldAttrs:
-        $ref: 'fieldattrs.yaml'
+        type: object
+        additionalProperties:
+          $ref: 'fieldattrs.yaml'
      fieldFormats:
        $ref: 'fieldformats.yaml'
      fields:
--- a/src/plugins/data_views/docs/openapi/components/schemas/fieldattrs.yaml
+++ b/src/plugins/data_views/docs/openapi/components/schemas/fieldattrs.yaml
@ -1,2 +1,13 @@
 type: object
-description: A map of field attributes by field name.
+description: A map of field attributes by field name.
+properties:
+  count:
+    type: integer
+    description: Popularity count for the field.
+  customDescription:
+    type: string
+    description: Custom description for the field.
+    maxLength: 300
+  customLabel:
+    type: string
+    description: Custom label for the field.
--- a/src/plugins/data_views/docs/openapi/paths/api@data_views@data_view@{viewid}@fields.yaml
+++ b/src/plugins/data_views/docs/openapi/paths/api@data_views@data_view@{viewid}@fields.yaml
@ -2,7 +2,7 @@ post:
  summary: Update data view fields metadata in the default space
  operationId: updateFieldsMetadataDefault
  description: >
-    Update fields presentation metadata such as count, customLabel and format.
+    Update fields presentation metadata such as count, customLabel, customDescription, and format.
    This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. You can update multiple fields in one request. Updates are merged with persisted metadata. To remove existing metadata, specify null as the value.
  tags:
    - data views