From 099b45908e1c7f654f37d371c01722e1a3339beb Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 19 Dec 2024 15:22:55 -0800 Subject: [PATCH] [DOCS] Edit usage and info API summaries (#3339) (#3348) (cherry picked from commit 742729d05d028448e155198c583f9611b5d56bd9) Co-authored-by: Lisa Cawley --- output/openapi/elasticsearch-openapi.json | 10 ++++--- output/schema/schema.json | 26 +++++++++---------- .../UpgradeTransformsRequest.ts | 20 +++++++++----- specification/xpack/info/XPackInfoRequest.ts | 9 +++++-- .../xpack/usage/XPackUsageRequest.ts | 6 +++-- 5 files changed, 43 insertions(+), 28 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 0c84a66c42..4d12799a9c 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -35832,8 +35832,8 @@ "tags": [ "transform" ], - "summary": "Upgrades all transforms", - "description": "This API identifies transforms that have a legacy configuration format and upgrades them to the latest version. It\nalso cleans up the internal data structures that store the transform state and checkpoints. The upgrade does not\naffect the source and destination indices. The upgrade also does not affect the roles that transforms use when\nElasticsearch security features are enabled; the role used to read source data and write to the destination index\nremains unchanged.", + "summary": "Upgrade all transforms", + "description": "Transforms are compatible across minor versions and between supported major versions.\nHowever, over time, the format of transform configuration information may change.\nThis API identifies transforms that have a legacy configuration format and upgrades them to the latest version.\nIt also cleans up the internal data structures that store the transform state and checkpoints.\nThe upgrade does not affect the source and destination indices.\nThe upgrade also does not affect the roles that transforms use when Elasticsearch security features are enabled; the role used to read source data and write to the destination index remains unchanged.\n\nIf a transform upgrade step fails, the upgrade stops and an error is returned about the underlying issue.\nResolve the issue then re-run the process again.\nA summary is returned when the upgrade is finished.\n\nTo ensure continuous transforms remain running during a major version upgrade of the cluster – for example, from 7.16 to 8.0 – it is recommended to upgrade transforms before upgrading the cluster.\nYou may want to perform a recent cluster backup prior to the upgrade.", "operationId": "transform-upgrade-transforms", "parameters": [ { @@ -37159,7 +37159,8 @@ "tags": [ "xpack" ], - "summary": "Provides general information about the installed X-Pack features", + "summary": "Get information", + "description": "The information provided by the API includes:\n\n* Build information including the build number and timestamp.\n* License information about the currently installed license.\n* Feature information for the features that are currently enabled and available under the current license.", "operationId": "xpack-info", "parameters": [ { @@ -37235,7 +37236,8 @@ "tags": [ "xpack" ], - "summary": "This API provides information about which features are currently enabled and available under the current license and some usage statistics", + "summary": "Get usage information", + "description": "Get information about the features that are currently enabled and available under the current license.\nThe API also provides some usage statistics.", "operationId": "xpack-usage", "parameters": [ { diff --git a/output/schema/schema.json b/output/schema/schema.json index f222abd68a..1f548cdcc7 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -20226,7 +20226,7 @@ "stability": "stable" } }, - "description": "Upgrades all transforms.\nThis API identifies transforms that have a legacy configuration format and upgrades them to the latest version. It\nalso cleans up the internal data structures that store the transform state and checkpoints. The upgrade does not\naffect the source and destination indices. The upgrade also does not affect the roles that transforms use when\nElasticsearch security features are enabled; the role used to read source data and write to the destination index\nremains unchanged.", + "description": "Upgrade all transforms.\nTransforms are compatible across minor versions and between supported major versions.\nHowever, over time, the format of transform configuration information may change.\nThis API identifies transforms that have a legacy configuration format and upgrades them to the latest version.\nIt also cleans up the internal data structures that store the transform state and checkpoints.\nThe upgrade does not affect the source and destination indices.\nThe upgrade also does not affect the roles that transforms use when Elasticsearch security features are enabled; the role used to read source data and write to the destination index remains unchanged.\n\nIf a transform upgrade step fails, the upgrade stops and an error is returned about the underlying issue.\nResolve the issue then re-run the process again.\nA summary is returned when the upgrade is finished.\n\nTo ensure continuous transforms remain running during a major version upgrade of the cluster – for example, from 7.16 to 8.0 – it is recommended to upgrade transforms before upgrading the cluster.\nYou may want to perform a recent cluster backup prior to the upgrade.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/upgrade-transforms.html", "name": "transform.upgrade_transforms", "privileges": { @@ -20864,13 +20864,12 @@ "stability": "stable" } }, - "description": "Provides general information about the installed X-Pack features.", + "description": "Get information.\nThe information provided by the API includes:\n\n* Build information including the build number and timestamp.\n* License information about the currently installed license.\n* Feature information for the features that are currently enabled and available under the current license.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/info-api.html", "name": "xpack.info", "privileges": { "cluster": [ - "monitor", - "manage" + "monitor" ] }, "request": { @@ -20904,13 +20903,12 @@ "stability": "stable" } }, - "description": "This API provides information about which features are currently enabled and available under the current license and some usage statistics.", + "description": "Get usage information.\nGet information about the features that are currently enabled and available under the current license.\nThe API also provides some usage statistics.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/usage-api.html", "name": "xpack.usage", "privileges": { "cluster": [ - "monitor", - "manage" + "monitor" ] }, "request": { @@ -213427,7 +213425,7 @@ "body": { "kind": "no_body" }, - "description": "Upgrades all transforms.\nThis API identifies transforms that have a legacy configuration format and upgrades them to the latest version. It\nalso cleans up the internal data structures that store the transform state and checkpoints. The upgrade does not\naffect the source and destination indices. The upgrade also does not affect the roles that transforms use when\nElasticsearch security features are enabled; the role used to read source data and write to the destination index\nremains unchanged.", + "description": "Upgrade all transforms.\nTransforms are compatible across minor versions and between supported major versions.\nHowever, over time, the format of transform configuration information may change.\nThis API identifies transforms that have a legacy configuration format and upgrades them to the latest version.\nIt also cleans up the internal data structures that store the transform state and checkpoints.\nThe upgrade does not affect the source and destination indices.\nThe upgrade also does not affect the roles that transforms use when Elasticsearch security features are enabled; the role used to read source data and write to the destination index remains unchanged.\n\nIf a transform upgrade step fails, the upgrade stops and an error is returned about the underlying issue.\nResolve the issue then re-run the process again.\nA summary is returned when the upgrade is finished.\n\nTo ensure continuous transforms remain running during a major version upgrade of the cluster – for example, from 7.16 to 8.0 – it is recommended to upgrade transforms before upgrading the cluster.\nYou may want to perform a recent cluster backup prior to the upgrade.", "inherits": { "type": { "name": "RequestBase", @@ -213467,7 +213465,7 @@ } } ], - "specLocation": "transform/upgrade_transforms/UpgradeTransformsRequest.ts#L23-L49" + "specLocation": "transform/upgrade_transforms/UpgradeTransformsRequest.ts#L23-L57" }, { "kind": "response", @@ -220001,7 +219999,7 @@ "body": { "kind": "no_body" }, - "description": "Provides general information about the installed X-Pack features.", + "description": "Get information.\nThe information provided by the API includes:\n\n* Build information including the build number and timestamp.\n* License information about the currently installed license.\n* Feature information for the features that are currently enabled and available under the current license.", "inherits": { "type": { "name": "RequestBase", @@ -220055,7 +220053,7 @@ } } ], - "specLocation": "xpack/info/XPackInfoRequest.ts#L22-L42" + "specLocation": "xpack/info/XPackInfoRequest.ts#L22-L47" }, { "kind": "response", @@ -220131,7 +220129,7 @@ "name": "XPackCategory", "namespace": "xpack.info" }, - "specLocation": "xpack/info/XPackInfoRequest.ts#L44-L48" + "specLocation": "xpack/info/XPackInfoRequest.ts#L49-L53" }, { "kind": "interface", @@ -222303,7 +222301,7 @@ "body": { "kind": "no_body" }, - "description": "This API provides information about which features are currently enabled and available under the current license and some usage statistics.", + "description": "Get usage information.\nGet information about the features that are currently enabled and available under the current license.\nThe API also provides some usage statistics.", "inherits": { "type": { "name": "RequestBase", @@ -222330,7 +222328,7 @@ } } ], - "specLocation": "xpack/usage/XPackUsageRequest.ts#L23-L38" + "specLocation": "xpack/usage/XPackUsageRequest.ts#L23-L40" }, { "kind": "response", diff --git a/specification/transform/upgrade_transforms/UpgradeTransformsRequest.ts b/specification/transform/upgrade_transforms/UpgradeTransformsRequest.ts index d4908da900..552dbc7f48 100644 --- a/specification/transform/upgrade_transforms/UpgradeTransformsRequest.ts +++ b/specification/transform/upgrade_transforms/UpgradeTransformsRequest.ts @@ -21,12 +21,20 @@ import { RequestBase } from '@_types/Base' import { Duration } from '@_types/Time' /** - * Upgrades all transforms. - * This API identifies transforms that have a legacy configuration format and upgrades them to the latest version. It - * also cleans up the internal data structures that store the transform state and checkpoints. The upgrade does not - * affect the source and destination indices. The upgrade also does not affect the roles that transforms use when - * Elasticsearch security features are enabled; the role used to read source data and write to the destination index - * remains unchanged. + * Upgrade all transforms. + * Transforms are compatible across minor versions and between supported major versions. + * However, over time, the format of transform configuration information may change. + * This API identifies transforms that have a legacy configuration format and upgrades them to the latest version. + * It also cleans up the internal data structures that store the transform state and checkpoints. + * The upgrade does not affect the source and destination indices. + * The upgrade also does not affect the roles that transforms use when Elasticsearch security features are enabled; the role used to read source data and write to the destination index remains unchanged. + * + * If a transform upgrade step fails, the upgrade stops and an error is returned about the underlying issue. + * Resolve the issue then re-run the process again. + * A summary is returned when the upgrade is finished. + * + * To ensure continuous transforms remain running during a major version upgrade of the cluster – for example, from 7.16 to 8.0 – it is recommended to upgrade transforms before upgrading the cluster. + * You may want to perform a recent cluster backup prior to the upgrade. * @rest_spec_name transform.upgrade_transforms * @availability stack since=7.16.0 stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/xpack/info/XPackInfoRequest.ts b/specification/xpack/info/XPackInfoRequest.ts index 1261113b5b..9221e3b97a 100644 --- a/specification/xpack/info/XPackInfoRequest.ts +++ b/specification/xpack/info/XPackInfoRequest.ts @@ -20,11 +20,16 @@ import { RequestBase } from '@_types/Base' /** - * Provides general information about the installed X-Pack features. + * Get information. + * The information provided by the API includes: + * + * * Build information including the build number and timestamp. + * * License information about the currently installed license. + * * Feature information for the features that are currently enabled and available under the current license. * @rest_spec_name xpack.info * @availability stack stability=stable * @availability serverless stability=stable visibility=private - * @cluster_privileges monitor,manage + * @cluster_privileges monitor */ export interface Request extends RequestBase { query_parameters: { diff --git a/specification/xpack/usage/XPackUsageRequest.ts b/specification/xpack/usage/XPackUsageRequest.ts index ec6e58c6ef..e515f43526 100644 --- a/specification/xpack/usage/XPackUsageRequest.ts +++ b/specification/xpack/usage/XPackUsageRequest.ts @@ -21,11 +21,13 @@ import { RequestBase } from '@_types/Base' import { Duration } from '@_types/Time' /** - * This API provides information about which features are currently enabled and available under the current license and some usage statistics. + * Get usage information. + * Get information about the features that are currently enabled and available under the current license. + * The API also provides some usage statistics. * @rest_spec_name xpack.usage * @availability stack stability=stable * @availability serverless stability=stable visibility=private - * @cluster_privileges monitor,manage + * @cluster_privileges monitor */ export interface Request extends RequestBase { query_parameters: {