updating the wording on api spec (#927)

Signed-off-by: Anton Rubin <[email protected]>

Author: AntonEliatra

spec/namespaces/_core.yaml

@@ -2307,7 +2307,7 @@ components:
             properties:
               scroll_id:
                 $ref: '../schemas/_common.yaml#/components/schemas/ScrollIds'
-            description: Comma-separated list of scroll IDs to clear if none was specified using the `scroll_id` parameter
+            description: A comma-separated list of scroll IDs to clear if none was specified using the `scroll_id` parameter
     count:
       content:
         application/json:
@@ -3567,7 +3567,7 @@ components:
       in: path
       name: scroll_id
       description: |-
-        Comma-separated list of scroll IDs to clear.
+        A comma-separated list of scroll IDs to clear.
         To clear all scroll IDs, use `_all`.
       required: true
       deprecated: true
@@ -3578,7 +3578,7 @@ components:
       in: path
       name: index
       description: |-
-        Comma-separated list of data streams, indexes, and aliases to search.
+        A comma-separated list of data streams, indexes, and aliases to search.
         Supports wildcards (`*`).
         To search all data streams and indexes, omit this parameter or use `*` or `_all`.
       required: true
@@ -3704,7 +3704,7 @@ components:
     create::path.id:
       in: path
       name: id
-      description: Unique identifier for the document.
+      description: The unique identifier for the document.
       required: true
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Id'
@@ -3765,7 +3765,7 @@ components:
     create::query.version_type:
       in: query
       name: version_type
-      description: 'Specific version type: `external`, `external_gte`.'
+      description: 'The specific version type: `external`, `external_gte`.'
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/VersionType'
       style: form
@@ -3782,10 +3782,10 @@ components:
     create_pit::path.index:
       name: index
       in: path
-      description: Comma-separated list of indexes; use `_all` or empty string to perform the operation on all indexes.
+      description: A comma-separated list of indexes; use `_all` or empty string to perform the operation on all indexes.
       schema:
         type: array
-        description: Comma-separated list of indexes; use `_all` or empty string to perform the operation on all indexes.
+        description: A comma-separated list of indexes; use `_all` or empty string to perform the operation on all indexes.
         items:
           type: string
       required: true
@@ -3819,15 +3819,15 @@ components:
     create_pit::query.routing:
       name: routing
       in: query
-      description: Comma-separated list of specific routing values.
+      description: A comma-separated list of specific routing values.
       style: form
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/RoutingInQueryString'
       explode: true
     delete::path.id:
       in: path
       name: id
-      description: Unique identifier for the document.
+      description: The unique identifier for the document.
       required: true
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Id'
@@ -3890,7 +3890,7 @@ components:
     delete::query.version_type:
       in: query
       name: version_type
-      description: 'Specific version type: `external`, `external_gte`.'
+      description: 'The specific version type: `external`, `external_gte`.'
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/VersionType'
       style: form
@@ -3908,7 +3908,7 @@ components:
       in: path
       name: index
       description: |-
-        Comma-separated list of data streams, indexes, and aliases to search.
+        A comma-separated list of data streams, indexes, and aliases to search.
         Supports wildcards (`*`).
         To search all data streams or indexes, omit this parameter or use `*` or `_all`.
       required: true
@@ -4263,7 +4263,7 @@ components:
       in: path
       name: index
       description: |-
-        Comma-separated list of data streams, indexes, and aliases.
+        A comma-separated list of data streams, indexes, and aliases.
         Supports wildcards (`*`).
       required: true
       schema:
@@ -4343,7 +4343,7 @@ components:
     exists::query.version_type:
       in: query
       name: version_type
-      description: 'Specific version type: `external`, `external_gte`.'
+      description: 'The specific version type: `external`, `external_gte`.'
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/VersionType'
       style: form
@@ -4359,7 +4359,7 @@ components:
       in: path
       name: index
       description: |-
-        Comma-separated list of data streams, indexes, and aliases.
+        A comma-separated list of data streams, indexes, and aliases.
         Supports wildcards (`*`).
       required: true
       schema:
@@ -4429,7 +4429,7 @@ components:
     exists_source::query.version_type:
       in: query
       name: version_type
-      description: 'Specific version type: `external`, `external_gte`.'
+      description: 'The specific version type: `external`, `external_gte`.'
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/VersionType'
       style: form
@@ -4545,7 +4545,7 @@ components:
     field_caps::path.index:
       in: path
       name: index
-      description: Comma-separated list of data streams, indexes, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indexes, omit this parameter or use * or `_all`.
+      description: A comma-separated list of data streams, indexes, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indexes, omit this parameter or use * or `_all`.
       required: true
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Indices'
@@ -4570,7 +4570,7 @@ components:
     field_caps::query.fields:
       in: query
       name: fields
-      description: Comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.
+      description: A comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Fields'
       style: form
@@ -4675,7 +4675,7 @@ components:
     get::query.version_type:
       in: query
       name: version_type
-      description: 'Specific version type: `internal`, `external`, `external_gte`.'
+      description: 'The specific version type: `internal`, `external`, `external_gte`.'
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/VersionType'
       style: form
@@ -4780,14 +4780,14 @@ components:
     get_source::query.version_type:
       in: query
       name: version_type
-      description: Specific version type. One of `internal`, `external`, `external_gte`.
+      description: The specific version type. One of `internal`, `external`, `external_gte`.
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/VersionType'
       style: form
     index::path.id:
       in: path
       name: id
-      description: Unique identifier for the document.
+      description: The unique identifier for the document.
       required: true
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Id'
@@ -4881,7 +4881,7 @@ components:
     index::query.version_type:
       in: query
       name: version_type
-      description: 'Specific version type: `external`, `external_gte`.'
+      description: 'The specific version type: `external`, `external_gte`.'
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/VersionType'
       style: form
@@ -4898,7 +4898,7 @@ components:
     mget::path.index:
       in: path
       name: index
-      description: Name of the index to retrieve documents from when `ids` are specified, or when a document in the `docs` array does not specify an index.
+      description: The name of the index to retrieve documents from when `ids` are specified, or when a document in the `docs` array does not specify an index.
       required: true
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/IndexName'
@@ -4968,7 +4968,7 @@ components:
     msearch::path.index:
       in: path
       name: index
-      description: Comma-separated list of data streams, indexes, and index aliases to search.
+      description: A comma-separated list of data streams, indexes, and index aliases to search.
       required: true
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Indices'
@@ -5032,7 +5032,7 @@ components:
       in: path
       name: index
       description: |-
-        Comma-separated list of data streams, indexes, and aliases to search.
+        A comma-separated list of data streams, indexes, and aliases to search.
         Supports wildcards (`*`).
         To search all data streams and indexes, omit this parameter or use `*`.
       required: true
@@ -5243,7 +5243,7 @@ components:
       in: path
       name: index
       description: |-
-        Comma-separated list of data streams, indexes, and index aliases used to limit the request. Wildcard (`*`) expressions are supported.
+        A comma-separated list of data streams, indexes, and index aliases used to limit the request. Wildcard (`*`) expressions are supported.
         To target all data streams and indexes in a cluster, omit this parameter or use `_all` or `*`.
       required: true
       schema:
@@ -5413,7 +5413,7 @@ components:
       in: path
       name: index
       description: |-
-        Comma-separated list of data streams, indexes, and aliases to search.
+        A comma-separated list of data streams, indexes, and aliases to search.
         Supports wildcards (`*`).
         To search all data streams and indexes, omit this parameter or use `*` or `_all`.
       required: true
@@ -5927,7 +5927,7 @@ components:
       in: path
       name: index
       description: |-
-        Comma-separated list of data streams, indexes,
+        A comma-separated list of data streams, indexes,
         and aliases to search. Supports wildcards (*).
       required: true
       schema:
@@ -6260,7 +6260,7 @@ components:
       in: path
       name: index
       description: |-
-        Comma-separated list of data streams, indexes, and aliases to search.
+        A comma-separated list of data streams, indexes, and aliases to search.
         Supports wildcards (`*`).
         To search all data streams or indexes, omit this parameter or use `*` or `_all`.
       required: true

spec/namespaces/cat.yaml

@@ -1335,7 +1335,7 @@ components:
       in: path
       name: index
       description: |-
-        Comma-separated list of data streams, indexes, and aliases used to limit the request.
+        A comma-separated list of data streams, indexes, and aliases used to limit the request.
         Supports wildcards (`*`). To target all data streams and indexes, omit this parameter or use `*` or `_all`.
       required: true
       schema: