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

# Backport

This will backport the following commits from `main` to `8.15`:
- [[Discover] Update data view API docs
(#187146)](#187146)

<!--- Backport version: 9.4.3 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Julia
Rechkunova","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-07-11T09:33:52Z","message":"[Discover]
Update data view API docs (#187146)\n\n- Closes
https://github.com/elastic/kibana/issues/187075\r\n\r\n##
Summary\r\n\r\nThis PR updates data view API docs. `customDescription`
was added
in\r\nhttps://github.com//pull/168577\r\n\r\n---------\r\n\r\nCo-authored-by:
Lisa Cawley <[email protected]>\r\nCo-authored-by: Davis McPhee
<[email protected]>","sha":"cd4a782cac7689b12087d2cdb0b2c9bcc676728e","branchLabelMapping":{"^v8.16.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Team:DataDiscovery","backport:prev-minor","v8.16.0"],"title":"[Discover]
Update data view API
docs","number":187146,"url":"https://github.com/elastic/kibana/pull/187146","mergeCommit":{"message":"[Discover]
Update data view API docs (#187146)\n\n- Closes
https://github.com/elastic/kibana/issues/187075\r\n\r\n##
Summary\r\n\r\nThis PR updates data view API docs. `customDescription`
was added
in\r\nhttps://github.com//pull/168577\r\n\r\n---------\r\n\r\nCo-authored-by:
Lisa Cawley <[email protected]>\r\nCo-authored-by: Davis McPhee
<[email protected]>","sha":"cd4a782cac7689b12087d2cdb0b2c9bcc676728e"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v8.16.0","branchLabelMappingKey":"^v8.16.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/187146","number":187146,"mergeCommit":{"message":"[Discover]
Update data view API docs (#187146)\n\n- Closes
https://github.com/elastic/kibana/issues/187075\r\n\r\n##
Summary\r\n\r\nThis PR updates data view API docs. `customDescription`
was added
in\r\nhttps://github.com//pull/168577\r\n\r\n---------\r\n\r\nCo-authored-by:
Lisa Cawley <[email protected]>\r\nCo-authored-by: Davis McPhee
<[email protected]>","sha":"cd4a782cac7689b12087d2cdb0b2c9bcc676728e"}}]}]
BACKPORT-->

Co-authored-by: Julia Rechkunova <[email protected]>

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.
 =====
 

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"
         }
     }
 }

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"

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:

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"
         }
     }
 }

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:

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:

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.

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