From 7c231ec471901de609268a43d3d43493f39143c0 Mon Sep 17 00:00:00 2001 From: Theo Truong Date: Tue, 17 Dec 2024 10:04:44 -0700 Subject: [PATCH 1/3] Dedupped param types and renamed `Paths and Http Methods` to `Endpoints` Signed-off-by: Theo Truong --- DEVELOPER_GUIDE.md | 10 +++++----- _api-reference/index.md | 2 +- .../workload-management/query-group-lifecycle-api.md | 8 ++++---- spec-insert/lib/api/parameter.rb | 4 ++-- .../renderers/{paths_and_methods.rb => endpoints.rb} | 6 +++--- spec-insert/lib/renderers/spec_insert.rb | 8 ++++---- .../{paths_and_methods.mustache => endpoints.mustache} | 2 +- spec-insert/lib/spec_hash.rb | 1 + .../{paths_and_http_methods.md => endpoints.md} | 4 ++-- .../spec/_fixtures/expected_output/param_tables.md | 2 +- .../input/{paths_and_http_methods.md => endpoints.md} | 2 +- spec-insert/spec/_fixtures/opensearch_spec.yaml | 10 ++++++++++ spec-insert/spec/doc_processor_spec.rb | 4 ++-- 13 files changed, 37 insertions(+), 26 deletions(-) rename spec-insert/lib/renderers/{paths_and_methods.rb => endpoints.rb} (68%) rename spec-insert/lib/renderers/templates/{paths_and_methods.mustache => endpoints.mustache} (79%) rename spec-insert/spec/_fixtures/expected_output/{paths_and_http_methods.md => endpoints.md} (71%) rename spec-insert/spec/_fixtures/input/{paths_and_http_methods.md => endpoints.md} (65%) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 9b0ec1c79d..cb039fd96a 100644 --- a/DEVELOPER_GUIDE.md +++ b/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 ``` diff --git a/_api-reference/index.md b/_api-reference/index.md index f87d40214e..831d987261 100644 --- a/_api-reference/index.md +++ b/_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 } diff --git a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md index 5f8ce4109b..d59fd4ecf2 100644 --- a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md +++ b/_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 ```json @@ -29,7 +29,7 @@ PUT /_wlm/query_group ```json @@ -41,7 +41,7 @@ PUT /_wlm/query_group ```json @@ -54,7 +54,7 @@ GET /_wlm/query_group/{name} ```json diff --git a/spec-insert/lib/api/parameter.rb b/spec-insert/lib/api/parameter.rb index fbd87fd50e..1bbe92c4ee 100644 --- a/spec-insert/lib/api/parameter.rb +++ b/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' diff --git a/spec-insert/lib/renderers/paths_and_methods.rb b/spec-insert/lib/renderers/endpoints.rb similarity index 68% rename from spec-insert/lib/renderers/paths_and_methods.rb rename to spec-insert/lib/renderers/endpoints.rb index 0685c03b36..f47c9b4193 100644 --- a/spec-insert/lib/renderers/paths_and_methods.rb +++ b/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 diff --git a/spec-insert/lib/renderers/spec_insert.rb b/spec-insert/lib/renderers/spec_insert.rb index 4d5ddb3803..57486a7f73 100644 --- a/spec-insert/lib/renderers/spec_insert.rb +++ b/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] arg_lines the lines between "" @@ -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 diff --git a/spec-insert/lib/renderers/templates/paths_and_methods.mustache b/spec-insert/lib/renderers/templates/endpoints.mustache similarity index 79% rename from spec-insert/lib/renderers/templates/paths_and_methods.mustache rename to spec-insert/lib/renderers/templates/endpoints.mustache index 3c2df68011..0541921aa8 100644 --- a/spec-insert/lib/renderers/templates/paths_and_methods.mustache +++ b/spec-insert/lib/renderers/templates/endpoints.mustache @@ -1,5 +1,5 @@ {{^omit_header}} -## Paths and HTTP methods +## Endpoints {{/omit_header}} ```json {{#operations}} diff --git a/spec-insert/lib/spec_hash.rb b/spec-insert/lib/spec_hash.rb index 06a872c9b9..619c530c32 100644 --- a/spec-insert/lib/spec_hash.rb +++ b/spec-insert/lib/spec_hash.rb @@ -22,6 +22,7 @@ class << self; attr_reader :raw; end class << self; attr_reader :parsed; end attr_reader :hash + delegate :to_s, to: :hash # @param [Hash] hash def initialize(hash = {}, parsed: true) diff --git a/spec-insert/spec/_fixtures/expected_output/paths_and_http_methods.md b/spec-insert/spec/_fixtures/expected_output/endpoints.md similarity index 71% rename from spec-insert/spec/_fixtures/expected_output/paths_and_http_methods.md rename to spec-insert/spec/_fixtures/expected_output/endpoints.md index 8ca1569b52..cffad018cb 100644 --- a/spec-insert/spec/_fixtures/expected_output/paths_and_http_methods.md +++ b/spec-insert/spec/_fixtures/expected_output/endpoints.md @@ -1,9 +1,9 @@ -## Paths and HTTP methods +## Endpoints ```json GET /_search POST /_search diff --git a/spec-insert/spec/_fixtures/expected_output/param_tables.md b/spec-insert/spec/_fixtures/expected_output/param_tables.md index 596f185458..5e4c05164e 100644 --- a/spec-insert/spec/_fixtures/expected_output/param_tables.md +++ b/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`. Query Parameters Example with Global Parameters, Pretty Print, and Custom Columns diff --git a/spec-insert/spec/_fixtures/input/paths_and_http_methods.md b/spec-insert/spec/_fixtures/input/endpoints.md similarity index 65% rename from spec-insert/spec/_fixtures/input/paths_and_http_methods.md rename to spec-insert/spec/_fixtures/input/endpoints.md index 0e92b8af8e..5b30459103 100644 --- a/spec-insert/spec/_fixtures/input/paths_and_http_methods.md +++ b/spec-insert/spec/_fixtures/input/endpoints.md @@ -1,6 +1,6 @@ diff --git a/spec-insert/spec/_fixtures/opensearch_spec.yaml b/spec-insert/spec/_fixtures/opensearch_spec.yaml index 7c67f27e69..c813cb4177 100644 --- a/spec-insert/spec/_fixtures/opensearch_spec.yaml +++ b/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 diff --git a/spec-insert/spec/doc_processor_spec.rb b/spec-insert/spec/doc_processor_spec.rb index 073613a2a9..76be789cf0 100644 --- a/spec-insert/spec/doc_processor_spec.rb +++ b/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 From 0b49e9c3707121962bd79dc28bda5c436a7dc30d Mon Sep 17 00:00:00 2001 From: Theo Truong Date: Tue, 17 Dec 2024 10:10:26 -0700 Subject: [PATCH 2/3] # rubocop Signed-off-by: Theo Truong --- spec-insert/lib/spec_hash.rb | 1 + 1 file changed, 1 insertion(+) diff --git a/spec-insert/lib/spec_hash.rb b/spec-insert/lib/spec_hash.rb index 619c530c32..0720250306 100644 --- a/spec-insert/lib/spec_hash.rb +++ b/spec-insert/lib/spec_hash.rb @@ -22,6 +22,7 @@ class << self; attr_reader :raw; end class << self; attr_reader :parsed; end attr_reader :hash + delegate :to_s, to: :hash # @param [Hash] hash From 17bef09d50a2abd08e7ddaa33ea3353e021ffd92 Mon Sep 17 00:00:00 2001 From: Theo Truong Date: Tue, 17 Dec 2024 10:29:25 -0700 Subject: [PATCH 3/3] # removed extra space Signed-off-by: Theo Truong --- DEVELOPER_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index cb039fd96a..5f6678904c 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -69,7 +69,7 @@ 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 `endpoints`. +- `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. ### Endpoints