[DOCS] Edit usage and info API summaries (#3339)

(cherry picked from commit 742729d)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -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

output/schema/schema.json

@@ -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: {

specification/transform/upgrade_transforms/UpgradeTransformsRequest.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: {