Add migration API examples (#3437) (#3448)

(cherry picked from commit 2d49d47)

Co-authored-by: Lisa Cawley <lcawley@elastic.co>

specification/_doc_ids/table.csv

@@ -306,7 +306,7 @@ mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping
 mean-reciprocal,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html#_mean_reciprocal_rank
 migrate-index-allocation-filters,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/migrate-index-allocation-filters.html
 migration-api-deprecation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/migration-api-deprecation.html
-migration-api-feature-upgrade,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/migration-api-feature-upgrade.html
+migration-api-feature-upgrade,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/feature-migration-api.html
 ml-apis,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ml-apis.html
 ml-classification,https://www.elastic.co/guide/en/machine-learning/{branch}/ml-dfa-classification.html
 ml-close-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ml-close-job.html

specification/migration/deprecations/DeprecationInfoRequest.ts

@@ -24,10 +24,12 @@ import { IndexName } from '@_types/common'
  * Get deprecation information.
  * Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.
  *
- * TIP: This APIs is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant.
+ * TIP: This APIs is designed for indirect use by the Upgrade Assistant.
+ * You are strongly recommended to use the Upgrade Assistant.
  * @rest_spec_name migration.deprecations
  * @availability stack since=6.1.0 stability=stable
  * @cluster_privileges manage
+ * @doc_id migration-api-deprecation
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/migration/deprecations/DeprecationInfoResponse.ts

@@ -22,10 +22,24 @@ import { Deprecation } from './types'
 
 export class Response {
   body: {
+    /**
+     * Cluster-level deprecation warnings.
+     */
     cluster_settings: Deprecation[]
+    /**
+     * Index warnings are sectioned off per index and can be filtered using an index-pattern in the query.
+     * This section includes warnings for the backing indices of data streams specified in the request path.
+     */
     index_settings: Dictionary<string, Deprecation[]>
     data_streams: Dictionary<string, Deprecation[]>
+    /**
+     * Node-level deprecation warnings.
+     * Since only a subset of your nodes might incorporate these settings, it is important to read the details section for more information about which nodes are affected.
+     */
     node_settings: Deprecation[]
+    /**
+     * Machine learning-related deprecation warnings.
+     */
     ml_settings: Deprecation[]
   }
 }

specification/migration/deprecations/DeprecationInfoResponseExample1.yaml

@@ -0,0 +1,19 @@
+# summary:
+description: >
+  An abbreviated response from `GET /_migration/deprecations`.
+# type: "response"
+# response_code: 200
+value:
+  cluster_settings:
+    - level: critical
+      message: "Cluster name cannot contain ':'"
+      url: 'https://www.elastic.co/guide/en/elasticsearch/reference/7.0/breaking-changes-7.0.html#_literal_literal_is_no_longer_allowed_in_cluster_name'
+      details: "This cluster is named [mycompany:logging], which contains the illegal character ':'."
+  node_settings: []
+  index_settings:
+    'logs:apache':
+      - level: warning
+        message: "Index name cannot contain ':'"
+        url: 'https://www.elastic.co/guide/en/elasticsearch/reference/7.0/breaking-changes-7.0.html#_literal_literal_is_no_longer_allowed_in_index_name'
+        details: "This index is named [logs:apache], which contains the illegal character ':'."
+  ml_settings: []

specification/migration/deprecations/types.ts

@@ -30,10 +30,17 @@ export enum DeprecationLevel {
 }
 
 export class Deprecation {
+  /**
+   * Optional details about the deprecation warning.
+   */
   details?: string
   /** The level property describes the significance of the issue. */
   level: DeprecationLevel
+  /** Descriptive information about the deprecation warning. */
   message: string
+  /**
+   * A link to the breaking change documentation, where you can find more information about this change.
+   */
   url: string
   resolve_during_rolling_upgrade: boolean
   _meta?: Dictionary<string, UserDefinedValue>

specification/migration/get_feature_upgrade_status/GetFeatureUpgradeStatusRequest.ts

@@ -25,10 +25,11 @@ import { RequestBase } from '@_types/Base'
  * Check which features need to be migrated and the status of any migrations that are in progress.
  *
  * TIP: This API is designed for indirect use by the Upgrade Assistant.
- * We strongly recommend you use the Upgrade Assistant.
+ * You are strongly recommended to use the Upgrade Assistant.
  * @rest_spec_name migration.get_feature_upgrade_status
  * @availability stack since=7.16.0 stability=stable
  * @index_privileges manage
  * @cluster_privileges manage
+ * @doc_id migration-api-feature-upgrade
  */
 export interface Request extends RequestBase {}