From e0c1e4bfb475899c28342c552e415c40e2ea4b99 Mon Sep 17 00:00:00 2001
From: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
Date: Thu, 11 Jul 2024 13:20:54 +0200
Subject: [PATCH] [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)](https://github.com/elastic/kibana/pull/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":"julia.rechkunova@elastic.co"},"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/elastic/kibana/pull/168577\r\n\r\n---------\r\n\r\nCo-authored-by:
Lisa Cawley <lcawley@elastic.co>\r\nCo-authored-by: Davis McPhee
<davismcphee@hotmail.com>","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/elastic/kibana/pull/168577\r\n\r\n---------\r\n\r\nCo-authored-by:
Lisa Cawley <lcawley@elastic.co>\r\nCo-authored-by: Davis McPhee
<davismcphee@hotmail.com>","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/elastic/kibana/pull/168577\r\n\r\n---------\r\n\r\nCo-authored-by:
Lisa Cawley <lcawley@elastic.co>\r\nCo-authored-by: Davis McPhee
<davismcphee@hotmail.com>","sha":"cd4a782cac7689b12087d2cdb0b2c9bcc676728e"}}]}]
BACKPORT-->

Co-authored-by: Julia Rechkunova <julia.rechkunova@elastic.co>
---
 docs/api/data-views/create.asciidoc           |  7 +++-
 docs/api/data-views/update-fields.asciidoc    |  5 ++-
 .../data_views/docs/openapi/bundled.json      | 40 +++++++++++++++----
 .../data_views/docs/openapi/bundled.yaml      | 29 +++++++++++---
 .../update_field_metadata_request.yaml        | 11 +++--
 .../create_data_view_request_object.yaml      |  4 +-
 .../schemas/data_view_response_object.yaml    |  4 +-
 .../components/schemas/fieldattrs.yaml        | 13 +++++-
 ...@data_views@data_view@{viewid}@fields.yaml |  2 +-
 9 files changed, 92 insertions(+), 23 deletions(-)

diff --git a/docs/api/data-views/create.asciidoc b/docs/api/data-views/create.asciidoc
index 2164983db11ea..32372639d2dbf 100644
--- 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.
 =====
 
diff --git a/docs/api/data-views/update-fields.asciidoc b/docs/api/data-views/update-fields.asciidoc
index 9b0b044238f36..0feacccb81863 100644
--- 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"
         }
     }
 }
diff --git a/src/plugins/data_views/docs/openapi/bundled.json b/src/plugins/data_views/docs/openapi/bundled.json
index 28893b86cef3f..5f2506c46e609 100644
--- 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"
diff --git a/src/plugins/data_views/docs/openapi/bundled.yaml b/src/plugins/data_views/docs/openapi/bundled.yaml
index dee19e6b1d67b..810f379b272e6 100644
--- 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:
diff --git 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
index ffa1eba13150f..e16e7e4d38dcb 100644
--- 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"
         }
     }
 }
\ No newline at end of file
diff --git 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
index ff2c34ed6d9ad..9ac5e0ddd796a 100644
--- 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:
diff --git 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
index 9d3c67201896b..f850c2f7c565e 100644
--- 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:
diff --git a/src/plugins/data_views/docs/openapi/components/schemas/fieldattrs.yaml b/src/plugins/data_views/docs/openapi/components/schemas/fieldattrs.yaml
index ede637d538a92..6d0cecd6b43b5 100644
--- 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.
\ No newline at end of file
+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.
\ No newline at end of file
diff --git 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
index 58dd10b88b5d3..3c2526c073513 100644
--- 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