From 7c72e100b896cf0ba43787151cd2e2a9e24d9b98 Mon Sep 17 00:00:00 2001 From: "Theo N. Truong" Date: Fri, 10 Jan 2025 13:13:03 -0700 Subject: [PATCH] [Spec-Insert] Params Table Updates (#9051) * [Spec-Insert] Renamed column `Type` to `Data Type` Signed-off-by: Theo Truong * - Added an empty line before params tables Signed-off-by: Theo Truong * - Added param table intro text Signed-off-by: Theo Truong * # Linting Signed-off-by: Theo Truong * # Revision 2 Signed-off-by: Theo Truong --------- Signed-off-by: Theo Truong --- spec-insert/lib/insert_arguments.rb | 4 +- .../lib/renderers/parameter_table_renderer.rb | 2 +- spec-insert/lib/renderers/path_parameters.rb | 11 +++++- spec-insert/lib/renderers/query_parameters.rb | 15 ++++++- .../templates/path_parameters.mustache | 3 ++ .../templates/query_parameters.mustache | 6 +-- .../_fixtures/expected_output/param_tables.md | 39 +++++++++++++++---- .../spec/_fixtures/input/param_tables.md | 11 +++++- .../spec/_fixtures/opensearch_spec.yaml | 7 ++++ 9 files changed, 80 insertions(+), 18 deletions(-) diff --git a/spec-insert/lib/insert_arguments.rb b/spec-insert/lib/insert_arguments.rb index 6216b8a3e0..10e11de2b0 100644 --- a/spec-insert/lib/insert_arguments.rb +++ b/spec-insert/lib/insert_arguments.rb @@ -2,8 +2,8 @@ # Doc Insert Arguments class InsertArguments - COLUMNS = %w[Parameter Description Required Type Default].freeze - DEFAULT_COLUMNS = %w[Parameter Type Description].freeze + COLUMNS = ['Parameter', 'Description', 'Required', 'Data type', 'Default'].freeze + DEFAULT_COLUMNS = ['Parameter', 'Data type', 'Description'].freeze attr_reader :raw # @param [Array] lines the lines between diff --git a/spec-insert/lib/renderers/parameter_table_renderer.rb b/spec-insert/lib/renderers/parameter_table_renderer.rb index 0deefaa9ba..6df4090ac4 100644 --- a/spec-insert/lib/renderers/parameter_table_renderer.rb +++ b/spec-insert/lib/renderers/parameter_table_renderer.rb @@ -28,7 +28,7 @@ def row(param) 'Parameter' => "`#{param.name}`#{'
_DEPRECATED_' if param.deprecated}", 'Description' => description(param), 'Required' => param.required ? 'Required' : nil, - 'Type' => param.doc_type, + 'Data type' => param.doc_type, 'Default' => param.default.nil? ? nil : "`#{param.default}`" } end diff --git a/spec-insert/lib/renderers/path_parameters.rb b/spec-insert/lib/renderers/path_parameters.rb index b1265bcf53..715ef7028c 100644 --- a/spec-insert/lib/renderers/path_parameters.rb +++ b/spec-insert/lib/renderers/path_parameters.rb @@ -8,7 +8,16 @@ class PathParameters < BaseMustacheRenderer self.template_file = "#{__dir__}/templates/path_parameters.mustache" def table - params = @action.arguments.select { |arg| arg.location == ArgLocation::PATH } ParameterTableRenderer.new(params, @args).render end + + def optional + params.none?(&:required) + end + + private + + def params + @params ||= @action.arguments.select { |arg| arg.location == ArgLocation::PATH } + end end diff --git a/spec-insert/lib/renderers/query_parameters.rb b/spec-insert/lib/renderers/query_parameters.rb index 37058ba5f1..f03544fce3 100644 --- a/spec-insert/lib/renderers/query_parameters.rb +++ b/spec-insert/lib/renderers/query_parameters.rb @@ -8,8 +8,19 @@ class QueryParameters < BaseMustacheRenderer self.template_file = "#{__dir__}/templates/query_parameters.mustache" def table - params = @action.arguments.select { |arg| arg.location == ArgLocation::QUERY } - params += Parameter.global if @args.include_global ParameterTableRenderer.new(params, @args).render end + + def optional + params.none?(&:required) + end + + private + + def params + return @params if defined?(@params) + @params = @action.arguments.select { |arg| arg.location == ArgLocation::QUERY } + @params += Parameter.global if @args.include_global + @params + end end diff --git a/spec-insert/lib/renderers/templates/path_parameters.mustache b/spec-insert/lib/renderers/templates/path_parameters.mustache index 9d9a2df9d4..ad69f4d589 100644 --- a/spec-insert/lib/renderers/templates/path_parameters.mustache +++ b/spec-insert/lib/renderers/templates/path_parameters.mustache @@ -1,4 +1,7 @@ {{^omit_header}} ## Path parameters + +The following table lists the available path parameters.{{#optional}} All path parameters are optional.{{/optional}} + {{/omit_header}} {{{table}}} \ No newline at end of file diff --git a/spec-insert/lib/renderers/templates/query_parameters.mustache b/spec-insert/lib/renderers/templates/query_parameters.mustache index d7331d8f5a..5cc7bc9241 100644 --- a/spec-insert/lib/renderers/templates/query_parameters.mustache +++ b/spec-insert/lib/renderers/templates/query_parameters.mustache @@ -1,7 +1,7 @@ {{^omit_header}} ## Query parameters -{{#optional}} -All query parameters are optional. -{{/optional}} + +The following table lists the available query parameters.{{#optional}} All query parameters are optional.{{/optional}} + {{/omit_header}} {{{table}}} \ No newline at end of file diff --git a/spec-insert/spec/_fixtures/expected_output/param_tables.md b/spec-insert/spec/_fixtures/expected_output/param_tables.md index 96bbcd363b..203ddf722c 100644 --- a/spec-insert/spec/_fixtures/expected_output/param_tables.md +++ b/spec-insert/spec/_fixtures/expected_output/param_tables.md @@ -5,7 +5,10 @@ api: search component: path_parameters --> ## Path parameters -Parameter | Type | Description + +The following table lists the available path parameters. All path parameters are optional. + +Parameter | Data type | Description :--- | :--- | :--- `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`. @@ -17,15 +20,18 @@ api: search component: query_parameters include_global: true pretty: true -columns: Type, Parameter, Description, Required, Default +columns: Data type, Parameter, Description, Required, Default --> ## Query parameters -| Type | Parameter | Description | Required | Default | -|:--------|:--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------|:---------|:--------| -| Boolean | `analyze_wildcard` | If true, wildcard and prefix queries are analyzed. This parameter can only be used when the q query string parameter is specified. | Required | `false` | -| String | `analyzer` | Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified. | | | -| Boolean | `pretty` | Whether to pretty format the returned JSON response. | | | -| Boolean | `human`
_DEPRECATED_ | _(Deprecated since 3.0: Use the `format` parameter instead.)_ Whether to return human readable values for statistics. | | `true` | + +The following table lists the available query parameters. + +| Data type | Parameter | Description | Required | Default | +|:----------|:--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------|:---------|:--------| +| Boolean | `analyze_wildcard` | If true, wildcard and prefix queries are analyzed. This parameter can only be used when the q query string parameter is specified. | Required | `false` | +| String | `analyzer` | Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified. | | | +| Boolean | `pretty` | Whether to pretty format the returned JSON response. | | | +| Boolean | `human`
_DEPRECATED_ | _(Deprecated since 3.0: Use the `format` parameter instead.)_ Whether to return human readable values for statistics. | | `true` | Query Parameters Example with only Parameter and Description Columns @@ -41,3 +47,20 @@ Parameter | Description `analyze_wildcard` | **(Required)** If true, wildcard and prefix queries are analyzed. This parameter can only be used when the q query string parameter is specified. _(Default: `false`)_ `analyzer` | Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified. + +Optional Params Text + + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +Parameter | Data type | Description +:--- | :--- | :--- +`pretty` | Boolean | Whether to pretty format the returned JSON response. +`human`
_DEPRECATED_ | Boolean | _(Deprecated since 3.0: Use the `format` parameter instead.)_ Whether to return human readable values for statistics. _(Default: `true`)_ + diff --git a/spec-insert/spec/_fixtures/input/param_tables.md b/spec-insert/spec/_fixtures/input/param_tables.md index d9f24e23f9..c10a9bb33f 100644 --- a/spec-insert/spec/_fixtures/input/param_tables.md +++ b/spec-insert/spec/_fixtures/input/param_tables.md @@ -18,7 +18,7 @@ api: search component: query_parameters include_global: true pretty: true -columns: Type, Parameter, Description, Required, Default +columns: Data type, Parameter, Description, Required, Default --> THIS TEXT SHOULD BE REPLACED @@ -37,3 +37,12 @@ SHOULD BE REPLACED + +Optional Params Text + + + diff --git a/spec-insert/spec/_fixtures/opensearch_spec.yaml b/spec-insert/spec/_fixtures/opensearch_spec.yaml index c813cb4177..3bafe57182 100644 --- a/spec-insert/spec/_fixtures/opensearch_spec.yaml +++ b/spec-insert/spec/_fixtures/opensearch_spec.yaml @@ -4,6 +4,13 @@ info: version: 1.0.0 x-api-version: 2.16.0 paths: + /_cat/health: + get: + operationId: cat_health.0 + x-operation-group: cat.health + parameters: + - $ref: '#/components/parameters/_global___query.pretty' + - $ref: '#/components/parameters/_global___query.human' /_search: get: operationId: search.0