[Spec Insert] Dedupped param types and renamed `Paths and Http Method…

…s` to `Endpoints` (#8966)

* Dedupped param types and renamed `Paths and Http Methods` to `Endpoints`

Signed-off-by: Theo Truong <theotr@amazon.com>

* # rubocop

Signed-off-by: Theo Truong <theotr@amazon.com>

* # removed extra space

Signed-off-by: Theo Truong <theotr@amazon.com>

---------

Signed-off-by: Theo Truong <theotr@amazon.com>
Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

DEVELOPER_GUIDE.md

@@ -7,7 +7,7 @@
 - [Spec insert components](#spec-insert-components)
   - [Query parameters](#query-parameters)
   - [Path parameters](#path-parameters)
-  - [Paths and HTTP methods](#paths-and-http-methods)
+  - [Endpoints](#endpoints)
 
 ## Introduction
 
@@ -69,15 +69,15 @@ The `spec-insert` plugin is run as part of the CI/CD pipeline to ensure that the
 ## Spec insert components
 All spec insert components accept the following arguments:
 - `api` (String; required): The name of the API to render the component from. This is equivalent to the `x-operation-group` field in the OpenSearch OpenAPI Spec.
-- `component` (String; required): The name of the component to render,  such as `query_parameters`, `path_parameters`, or `paths_and_http_methods`.
+- `component` (String; required): The name of the component to render, such as `query_parameters`, `path_parameters`, or `endpoints`.
 - `omit_header` (Boolean; Default is `false`): If set to `true`, the markdown header of the component will not be rendered.
 
-### Paths and HTTP methods
-To insert paths and HTTP methods for the `search` API, use the following snippet:
+### Endpoints
+To insert endpoints for the `search` API, use the following snippet:
 ```markdown
 <!-- spec_insert_start
 api: search
-component: paths_and_http_methods
+component: endpoints
 -->
 <!-- spec_insert_end -->
 ```

_api-reference/index.md

@@ -15,7 +15,7 @@ redirect_from:
 **Introduced 1.0**
 {: .label .label-purple }
 
-You can use REST APIs for most operations in OpenSearch. In this reference, we provide a description of the API, and details that include the paths and HTTP methods, supported parameters, and example requests and responses.
+You can use REST APIs for most operations in OpenSearch. In this reference, we provide a description of the API, and details that include the endpoints, supported parameters, and example requests and responses.
 
 This reference includes the REST APIs supported by OpenSearch. If a REST API is missing, please provide feedback or submit a pull request in GitHub.
 {: .tip }

_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md

@@ -17,7 +17,7 @@ The Query Group Lifecycle API creates, updates, retrieves, and deletes query gro
 
 <!-- spec_insert_start
 api: wlm.create_query_group
-component: paths_and_http_methods
+component: endpoints
 omit_header: true
 -->
 ```json
@@ -29,7 +29,7 @@ PUT /_wlm/query_group
 
 <!-- spec_insert_start
 api: wlm.create_query_group
-component: paths_and_http_methods
+component: endpoints
 omit_header: true
 -->
 ```json
@@ -41,7 +41,7 @@ PUT /_wlm/query_group
 
 <!-- spec_insert_start
 api: wlm.get_query_group
-component: paths_and_http_methods
+component: endpoints
 omit_header: true
 -->
 ```json
@@ -54,7 +54,7 @@ GET /_wlm/query_group/{name}
 
 <!-- spec_insert_start
 api: wlm.create_query_group
-component: paths_and_http_methods
+component: endpoints
 omit_header: true
 -->
 ```json

spec-insert/lib/api/parameter.rb

@@ -34,7 +34,7 @@ def initialize(name:, description:, required:, schema:, default:, deprecated:, d
     @description = description
     @required = required
     @schema = schema
-    @doc_type = get_doc_type(schema).gsub('String / List', 'List').gsub('List / String', 'List')
+    @doc_type = get_doc_type(schema)
     @default = default
     @deprecated = deprecated
     @deprecation_message = deprecation_message
@@ -47,7 +47,7 @@ def initialize(name:, description:, required:, schema:, default:, deprecated:, d
   def get_doc_type(schema)
     return nil if schema.nil?
     union = schema.anyOf || schema.oneOf
-    return union.map { |sch| get_doc_type(sch) }.join(' / ') unless union.nil?
+    return union.map { |sch| get_doc_type(sch) }.sort.uniq.join(' or ') if union.present?
     return 'Integer' if schema.type == 'integer'
     return 'Float' if schema.type == 'number'
     return 'Boolean' if schema.type == 'boolean'

spec-insert/lib/renderers/paths_and_methods.rb → spec-insert/lib/renderers/endpoints.rb

@@ -2,9 +2,9 @@
 
 require_relative 'base_mustache_renderer'
 
-# Renders paths and http methods
-class PathsAndMethods < BaseMustacheRenderer
-  self.template_file = "#{__dir__}/templates/paths_and_methods.mustache"
+# Renders Endpoints
+class Endpoints < BaseMustacheRenderer
+  self.template_file = "#{__dir__}/templates/endpoints.mustache"
 
   def operations
     ljust = @action.operations.map { |op| op.http_verb.length }.max

spec-insert/lib/renderers/spec_insert.rb

@@ -4,13 +4,13 @@
 require_relative '../insert_arguments'
 require_relative '../api/action'
 require_relative '../spec_insert_error'
-require_relative 'paths_and_methods'
+require_relative 'endpoints'
 require_relative 'path_parameters'
 require_relative 'query_parameters'
 
 # Class to render spec insertions
 class SpecInsert < BaseMustacheRenderer
-  COMPONENTS = Set.new(%w[query_params path_params paths_and_http_methods]).freeze
+  COMPONENTS = Set.new(%w[query_params path_params endpoints]).freeze
   self.template_file = "#{__dir__}/templates/spec_insert.mustache"
 
   # @param [Array<String>] arg_lines the lines between "<!-- doc_insert_start" and "-->"
@@ -33,8 +33,8 @@ def content
       QueryParameters.new(@action, @args).render
     when :path_parameters
       PathParameters.new(@action, @args).render
-    when :paths_and_http_methods
-      PathsAndMethods.new(@action, @args).render
+    when :endpoints
+      Endpoints.new(@action, @args).render
     else
       raise SpecInsertError, "Invalid component: #{@args.component}"
     end

spec-insert/lib/renderers/templates/paths_and_methods.mustache → spec-insert/lib/renderers/templates/endpoints.mustache

@@ -1,5 +1,5 @@
 {{^omit_header}}
-## Paths and HTTP methods
+## Endpoints
 {{/omit_header}}
 ```json
 {{#operations}}

spec-insert/lib/spec_hash.rb

@@ -23,6 +23,8 @@ class << self; attr_reader :parsed; end
 
   attr_reader :hash
 
+  delegate :to_s, to: :hash
+
   # @param [Hash] hash
   def initialize(hash = {}, parsed: true)
     @hash = parsed ? hash : parse(hash)

spec-insert/spec/_fixtures/expected_output/paths_and_http_methods.md → spec-insert/spec/_fixtures/expected_output/endpoints.md

@@ -1,9 +1,9 @@
 
 <!-- spec_insert_start
 api: search
-component: paths_and_http_methods
+component: endpoints
 -->
-## Paths and HTTP methods
+## Endpoints
 ```json
 GET  /_search
 POST /_search

spec-insert/spec/_fixtures/expected_output/param_tables.md

@@ -7,7 +7,7 @@ component: path_parameters
 ## Path parameters
 Parameter | Type | Description
 :--- | :--- | :---
-`index` | List | 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`.
+`index` | List or String | 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`.
 <!-- spec_insert_end -->
 
 Query Parameters Example with Global Parameters, Pretty Print, and Custom Columns

spec-insert/spec/_fixtures/input/paths_and_http_methods.md → spec-insert/spec/_fixtures/input/endpoints.md

@@ -1,6 +1,6 @@
 
 <!-- spec_insert_start
 api: search
-component: paths_and_http_methods
+component: endpoints
 -->
 <!-- spec_insert_end -->

spec-insert/spec/_fixtures/opensearch_spec.yaml

@@ -112,9 +112,19 @@ components:
     _common___Indices:
       oneOf:
         - $ref: '#/components/schemas/_common___IndexName'
+        - $ref: '#/components/schemas/_common___SpecialIndices'
         - type: array
           items:
             $ref: '#/components/schemas/_common___IndexName'
 
     _common___IndexName:
       type: string
+
+    _common___SpecialIndices:
+      oneOf:
+        - type: string
+          const: _all
+        - type: string
+          const: _any
+        - type: string
+          const: _none

spec-insert/spec/doc_processor_spec.rb

@@ -18,7 +18,7 @@ def test_file(file_name)
     test_file('param_tables')
   end
 
-  it 'inserts the paths and http methods correctly' do
-    test_file('paths_and_http_methods')
+  it 'inserts the Endpoints correctly' do
+    test_file('endpoints')
   end
 end