- Pipes for compact tables

Signed-off-by: Theo Truong <[email protected]>
opensearch-project · Jan 16, 2025 · a1e9e4f · a1e9e4f
1 parent b9b00e2
commit a1e9e4f
Show file tree

Hide file tree

Showing 5 changed files with 119 additions and 33 deletions.
diff --git a/spec-insert/lib/insert_arguments.rb b/spec-insert/lib/insert_arguments.rb
@@ -2,8 +2,6 @@
 
 # Doc Insert Arguments
 class InsertArguments
-  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 -->
@@ -27,10 +25,7 @@ def component
 
   # @return [Array<String>]
   def columns
-    cols = parse_array(@raw['columns']) || DEFAULT_COLUMNS
-    invalid = cols - COLUMNS
-    raise ArgumentError, "Invalid column(s): #{invalid.join(', ')}" unless invalid.empty?
-    cols
+    parse_array(@raw['columns']) || []
   end
 
   # @return [Boolean]

diff --git a/spec-insert/lib/renderers/parameter_table_renderer.rb b/spec-insert/lib/renderers/parameter_table_renderer.rb
@@ -4,14 +4,15 @@
 
 # Renders a table of parameters of an API action
 class ParameterTableRenderer
+  COLUMNS = ['Parameter', 'Description', 'Required', 'Data type', 'Default'].freeze
+  DEFAULT_COLUMNS = ['Parameter', 'Data type', 'Description'].freeze
+
   # @param [Array<Parameter>] parameters
   # @param [InsertArguments] args
   def initialize(parameters, args)
-    @columns = args.columns
+    @parameters = filter_parameters(parameters, args)
+    @columns = determine_columns(args)
     @pretty = args.pretty
-    @parameters = parameters
-    @parameters = @parameters.reject(&:deprecated) unless args.include_deprecated
-    @parameters = @parameters.sort_by { |arg| [arg.required ? 0 : 1, arg.deprecated ? 1 : 0, arg.name] }
   end
 
   # @return [String]
@@ -23,23 +24,68 @@ def render
 
   private
 
+  # @param [InsertArguments] args
+  def determine_columns(args)
+    if args.columns.present?
+      invalid = args.columns - COLUMNS
+      raise ArgumentError, "Invalid column(s): #{invalid.join(', ')}." unless invalid.empty?
+      return args.columns
+    end
+
+    required = @parameters.any?(&:required) ? 'Required' : nil
+    default = @parameters.any? { |p| p.default.present? } ? 'Default' : nil
+    ['Parameter', required, 'Data type', 'Description', default].compact
+  end
+
+  # @param [Array<Parameter>] parameters
+  # @param [InsertArguments] args
+  def filter_parameters(parameters, args)
+    parameters = parameters.reject(&:deprecated) unless args.include_deprecated
+    parameters.sort_by { |arg| [arg.required ? 0 : 1, arg.deprecated ? 1 : 0, arg.name] }
+  end
+
   def row(param)
     {
       'Parameter' => "`#{param.name}`#{' <br> _DEPRECATED_' if param.deprecated}",
       'Description' => description(param),
       'Required' => param.required ? 'Required' : nil,
       'Data type' => param.doc_type,
-      'Default' => param.default.nil? ? nil : "`#{param.default}`"
+      'Default' => param.default.nil? ? 'N/A' : "`#{param.default}`"
     }
   end
 
+  # @param [Parameter] param
   def description(param)
     deprecation = deprecation(param)
     required = param.required && @columns.exclude?('Required') ? '**(Required)** ' : ''
     description = param.description.gsub("\n", ' ')
+    valid_values = valid_values(param)
     default = param.default.nil? || @columns.include?('Default') ? '' : " _(Default: `#{param.default}`)_"
 
-    "#{deprecation}#{required}#{description}#{default}"
+    "#{deprecation}#{required}#{description}#{default}#{valid_values}"
+  end
+
+  # @param [Parameter] param
+  def valid_values(param)
+    enums = extract_enum_values(param.schema)&.compact
+    return '' unless enums.present?
+    if enums.none? { |enum| enum[:description].present? }
+      " <br> Valid values are: #{enums.map { |enum| "`#{enum[:value]}`" }.join(', ')}"
+    else
+      " <br> Valid values are: <br> #{enums.map { |enum| "- `#{enum[:value]}`: #{enum[:description]}" }
+                                           .join(' </br> ')}"
+    end
+  end
+
+  # @param [SpecHash] schema
+  # @return [Hash]
+  def extract_enum_values(schema)
+    return schema.enum.map { |value| { value: } } if schema.enum.present?
+    if schema.const.present?
+      { value: schema.const, description: schema.description }
+    elsif schema.oneOf.present?
+      schema.oneOf.map { |sch| extract_enum_values(sch) }.flatten
+    end
   end
 
   def deprecation(param)

diff --git a/spec-insert/lib/renderers/table_renderer.rb b/spec-insert/lib/renderers/table_renderer.rb
@@ -41,18 +41,18 @@ def calculate_column_widths
 
   def render_column
     columns = @column.map { |column| column.title.ljust(column.width) }.join(' | ')
-    @pretty ? "| #{columns} |" : columns
+    "| #{columns} |"
   end
 
   def render_divider
     dividers = @column.map { |column| ":#{'-' * [column.width + 1, 3].max}" }
-    @pretty ? "|#{dividers.join('|')}|" : dividers.join(' | ')
+    @pretty ? "|#{dividers.join('|')}|" : "| #{dividers.join(' | ')} |"
   end
 
   def render_rows
     @rows.map do |row|
       cells = @column.map { |column| row[column.key].to_s.ljust(column.width).gsub('|', '\|') }.join(' | ')
-      @pretty ? "| #{cells} |" : cells
+      "| #{cells} |"
     end
   end
 end
diff --git a/spec-insert/spec/_fixtures/expected_output/param_tables.md b/spec-insert/spec/_fixtures/expected_output/param_tables.md
@@ -8,9 +8,9 @@ component: path_parameters
 
 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`.
+| 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`. <br> Valid values are: `_all`, `_any`, `_none` |
 <!-- spec_insert_end -->
 
 Query Parameters Example with Global Parameters, Pretty Print, and Custom Columns
@@ -26,12 +26,13 @@ columns: Data type, Parameter, Description, Required, Default
 
 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`  |
+| 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.              |          | N/A     |
+| List or String | `expand_wildcards`        | Comma-separated list of expand wildcard options. <br> Valid values are: `open`, `closed`, `none`, `all`                            |          | N/A     |
+| Boolean        | `pretty`                  | Whether to pretty format the returned JSON response.                                                                               |          | N/A     |
+| 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
@@ -42,10 +43,11 @@ component: query_parameters
 columns: Parameter, Description
 omit_header: true
 -->
-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.
+| 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. |
+| `expand_wildcards` | Comma-separated list of expand wildcard options. <br> Valid values are: `open`, `closed`, `none`, `all` |
 <!-- spec_insert_end -->
 
 Optional Params Text
@@ -57,10 +59,11 @@ include_global: true
 -->
 ## Query parameters
 
-The following table lists the available query parameters. All query parameters are optional.
+The following table lists the available query parameters.
 
-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`)_
+| Parameter | Required | Data type | Description | Default |
+| :--- | :--- | :--- | :--- | :--- |
+| `expand_wildcard` | Required | String | Whether to expand wildcard expression to concrete indices that are open, closed, or both. <br> Valid values are: <br> - `open`: Expand wildcards to open indices only. </br> - `closed`: Expand wildcards to closed indices only. </br> - `none`: Do not expand wildcards. | N/A |
+| `pretty` |  | Boolean | Whether to pretty format the returned JSON response. | N/A |
+| `human` <br> _DEPRECATED_ |  | Boolean | _(Deprecated since 3.0: Use the `format` parameter instead.)_ Whether to return human readable values for statistics. | `true` |
 <!-- spec_insert_end -->
diff --git a/spec-insert/spec/_fixtures/opensearch_spec.yaml b/spec-insert/spec/_fixtures/opensearch_spec.yaml
@@ -11,6 +11,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/_global___query.pretty'
         - $ref: '#/components/parameters/_global___query.human'
+        - $ref: '#/components/parameters/cat.health___query.expand_wildcard'
   /_search:
     get:
       operationId: search.0
@@ -32,6 +33,7 @@ paths:
       parameters:
           - $ref: '#/components/parameters/search___query.analyze_wildcard'
           - $ref: '#/components/parameters/search___query.analyzer'
+          - $ref: '#/components/parameters/search___query.expand_wildcards'
   /{index}/_search:
     get:
       operationId: search.2
@@ -44,6 +46,7 @@ paths:
         - $ref: '#/components/parameters/search___path.index'
         - $ref: '#/components/parameters/search___query.analyze_wildcard'
         - $ref: '#/components/parameters/search___query.analyzer'
+        - $ref: '#/components/parameters/search___query.expand_wildcards'
     post:
       operationId: search.3
       x-operation-group: search
@@ -55,6 +58,7 @@ paths:
         - $ref: '#/components/parameters/search___path.index'
         - $ref: '#/components/parameters/search___query.analyze_wildcard'
         - $ref: '#/components/parameters/search___query.analyzer'
+        - $ref: '#/components/parameters/search___query.expand_wildcards'
 components:
 
   parameters:
@@ -80,6 +84,24 @@ components:
       x-version-deprecated: '3.0'
       x-deprecation-message: Use the `format` parameter instead.
 
+    cat.health___query.expand_wildcard:
+      in: query
+      required: true
+      name: expand_wildcard
+      description: |-
+          Whether to expand wildcard expression to concrete indices that are open, closed, or both.
+      schema:
+        oneOf:
+          - type: string
+            const: open
+            description: Expand wildcards to open indices only.
+          - type: string
+            const: closed
+            description: Expand wildcards to closed indices only.
+          - type: string
+            const: none
+            description: Do not expand wildcards.
+
     search___path.index:
       in: path
       name: index
@@ -114,6 +136,18 @@ components:
         type: string
       style: form
 
+    search___query.expand_wildcards:
+      in: query
+      name: expand_wildcards
+      description: |-
+        Comma-separated list of expand wildcard options.
+      schema:
+        oneOf:
+          - $ref: '#/components/schemas/_common___ExpandWildcardsCompact'
+          - type: array
+            items:
+              $ref: '#/components/schemas/_common___ExpandWildcardsCompact'
+
   schemas:
 
     _common___Indices:
@@ -135,3 +169,11 @@ components:
           const: _any
         - type: string
           const: _none
+
+    _common___ExpandWildcardsCompact:
+      type: string
+      enum:
+        - open
+        - closed
+        - none
+        - all