[Spec-Insert] Params Table Updates (#9051)

* [Spec-Insert] Renamed column `Type` to `Data Type` Signed-off-by: Theo Truong <[email protected]> * - Added an empty line before params tables Signed-off-by: Theo Truong <[email protected]> * - Added param table intro text Signed-off-by: Theo Truong <[email protected]> * # Linting Signed-off-by: Theo Truong <[email protected]> * # Revision 2 Signed-off-by: Theo Truong <[email protected]> --------- Signed-off-by: Theo Truong <[email protected]>
opensearch-project · Jan 10, 2025 · 7c72e10 · 7c72e10
1 parent 2119acf
commit 7c72e10
Show file tree

Hide file tree

Showing 9 changed files with 80 additions and 18 deletions.
diff --git 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<String>] lines the lines between <!-- doc_insert_start and -->

diff --git 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}`#{' <br> _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
@@ -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
@@ -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
@@ -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}}}
diff --git 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}}}
diff --git 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`.
 <!-- spec_insert_end -->
@@ -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` <br> _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` <br> _DEPRECATED_ | _(Deprecated since 3.0: Use the `format` parameter instead.)_ Whether to return human readable values for statistics.              |          | `true`  |
 <!-- spec_insert_end -->
 
 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.
 <!-- spec_insert_end -->
+
+Optional Params Text
+
+<!-- spec_insert_start
+api: cat.health
+component: query_parameters
+include_global: true
+-->
+## 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` <br> _DEPRECATED_ | Boolean | _(Deprecated since 3.0: Use the `format` parameter instead.)_ Whether to return human readable values for statistics. _(Default: `true`)_
+<!-- spec_insert_end -->
diff --git 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
 <!-- spec_insert_end -->
@@ -37,3 +37,12 @@ SHOULD
 BE
 REPLACED
 <!-- spec_insert_end -->
+
+Optional Params Text
+
+<!-- spec_insert_start
+api: cat.health
+component: query_parameters
+include_global: true
+-->
+<!-- spec_insert_end -->
diff --git 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