From 70b7eef64447edaf4f81c369e37ad4b925e1c683 Mon Sep 17 00:00:00 2001 From: "Theo N. Truong" Date: Fri, 15 Nov 2024 10:48:46 -0700 Subject: [PATCH] [ Jekyll ] [ SpecInsert ] omit_header (#8766) * Spec Insert A program that insert API Components generated from the OpenSearch OpenAPI Spec into markdown files Signed-off-by: Theo Truong * # vale:reviewdog Signed-off-by: Theo Truong * # Correction on cron job run time. Signed-off-by: Theo Truong * Apply suggestions from code review Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Daniel (dB.) Doubrovkine Signed-off-by: Theo N. Truong * Added `omit_header` argument for Spec Insert components (Some minor refactoring to DRY the code as well) Signed-off-by: Theo Truong * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --------- Signed-off-by: Theo Truong Signed-off-by: Theo N. Truong Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Daniel (dB.) Doubrovkine --- DEVELOPER_GUIDE.md | 68 +++++++++---------- spec-insert/lib/insert_arguments.rb | 5 ++ .../lib/renderers/base_mustache_renderer.rb | 14 ++-- .../lib/renderers/parameter_table_renderer.rb | 1 - spec-insert/lib/renderers/path_parameters.rb | 11 +-- .../lib/renderers/paths_and_methods.rb | 6 -- spec-insert/lib/renderers/query_parameters.rb | 16 +---- spec-insert/lib/renderers/spec_insert.rb | 8 +-- .../templates/path_parameters.mustache | 2 + .../templates/paths_and_methods.mustache | 2 + .../templates/query_parameters.mustache | 2 + .../_fixtures/expected_output/param_tables.md | 2 +- .../spec/_fixtures/input/param_tables.md | 1 + 13 files changed, 63 insertions(+), 75 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index f414fe0020..18de000473 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -1,12 +1,13 @@ # Developer guide - - [Introduction](#introduction) - - [Starting the Jekyll server locally](#starting-the-jekyll-server-locally) - - [Using the spec-insert Jekyll plugin](#using-the-spec-insert-jekyll-plugin) - - [Inserting query parameters](#inserting-query-parameters) - - [Inserting path parameters](#inserting-path-parameters) - - [Inserting paths and HTTP methods](#inserting-paths-and-http-methods) - - [Ignoring files and folders](#ignoring-files-and-folders) - - [CI/CD](#cicd) +- [Introduction](#introduction) +- [Starting the Jekyll server locally](#starting-the-jekyll-server-locally) +- [Using the spec-insert Jekyll plugin](#using-the-spec-insert-jekyll-plugin) + - [Ignoring files and folders](#ignoring-files-and-folders) +- [CI/CD](#cicd) +- [Spec insert components](#spec-insert-components) + - [Query parameters](#query-parameters) + - [Path parameters](#path-parameters) + - [Paths and HTTP methods](#paths-and-http-methods) ## Introduction @@ -31,7 +32,7 @@ Edit your Markdown file and insert the following snippet where you want render a This is where the API component will be inserted. @@ -59,10 +60,20 @@ The plugin will pull the newest OpenSearch API spec from its [repository](https: bundle exec jekyll spec-insert --refresh-spec ``` -### Inserting query parameters +### Ignoring files and folders +The `spec-insert` plugin ignores all files and folders listed in the [./_config.yml#exclude](./_config.yml) list, which is also the list of files and folders that Jekyll ignores. -To insert the API query parameters table, use the following snippet: +## CI/CD +The `spec-insert` plugin is run as part of the CI/CD pipeline to ensure that the API components are up to date in the documentation. This is performed through the [update-api-components.yml](.github/workflows/update-api-components.yml) GitHub Actions workflow, which creates a pull request containing the updated API components every Sunday. +## 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`. +- `omit_header` (Boolean; Default is `false`): If set to `true`, the markdown header of the component will not be rendered. + +### Query parameters +To insert the API query parameters table of the `cat.indices` API, use the following snippet: ```markdown ``` -This will insert the query parameters of the `cat.indices` API into the `.md` file with three default columns: `Parameter`, `Type`, and `Description`. There are five columns that can be inserted: `Parameter`, `Type`, `Description`, `Required`, and `Default`. When `Required`/`Default` is not chosen, the information will be written in the `Description` column. - -You can customize the query parameters table with the following columns: +This will insert the query parameters of the `cat.indices` API into the `.md` file with three default columns: `Parameter`, `Type`, and `Description`. You can customize the query parameters table by adding the `columns` argument which accepts a comma-separated list of column names. The available column names are: - `Parameter` - `Type` - `Description` -- `Required` +- `Required` - `Default` - You can also customize this component with the following settings: - +_When `Required`/`Default` is not chosen, the information will be written in the `Description` column._ + +You can also customize this component with the following settings: + - `include_global` (Boolean; default is `false`): Includes global query parameters in the table. - `include_deprecated` (Boolean; default is `true`): Includes deprecated parameters in the table. - `pretty` (Boolean; default is `false`): Renders the table in the pretty format instead of the compact format. @@ -100,10 +111,8 @@ pretty: true ``` -### Inserting path parameters - -To insert the `indices.create` API path parameters table, use the following snippet: - +### Path parameters +To insert path parameters table of the `indices.create` API, use the following snippet: ```markdown ``` +This table behaves the same as the query parameters table except that it does not accept the `include_global` argument. -This table behaves identically to the query parameters table except that it does not accept the `include_global` argument. - -### Inserting paths and HTTP methods - +### Paths and HTTP methods To insert paths and HTTP methods for the `search` API, use the following snippet: - ```markdown -``` - -### Ignoring files and folders - -The `spec-insert` plugin ignores all files and folders listed in the [./_config.yml#exclude](./_config.yml) list, which is also the list of files and folders that Jekyll ignores. - -### CI/CD - -The `spec-insert` plugin is run as part of the CI/CD pipeline to ensure that the API components are up to date in the documentation. This is performed through the [update-api-components.yml](.github/workflows/update-api-components.yml) GitHub Actions workflow, which creates a pull request containing the updated API components every Sunday. +``` \ No newline at end of file diff --git a/spec-insert/lib/insert_arguments.rb b/spec-insert/lib/insert_arguments.rb index 08b9b4dc9b..6216b8a3e0 100644 --- a/spec-insert/lib/insert_arguments.rb +++ b/spec-insert/lib/insert_arguments.rb @@ -48,6 +48,11 @@ def include_deprecated parse_boolean(@raw['include_deprecated'], default: true) end + # @return [Boolean] + def omit_header + parse_boolean(@raw['omit_header'], default: false) + end + private # @param [String] value comma-separated array diff --git a/spec-insert/lib/renderers/base_mustache_renderer.rb b/spec-insert/lib/renderers/base_mustache_renderer.rb index 2ebd83783d..b3d756304c 100644 --- a/spec-insert/lib/renderers/base_mustache_renderer.rb +++ b/spec-insert/lib/renderers/base_mustache_renderer.rb @@ -6,13 +6,15 @@ class BaseMustacheRenderer < Mustache self.template_path = "#{__dir__}/templates" - def initialize(output_file = nil) - @output_file = output_file - super + # @param [Action] action API Action + # @param [InsertArguments] args + def initialize(action, args) + super() + @action = action + @args = args end - def generate - raise 'Output file not specified' unless @output_file - @output_file&.write(render) + def omit_header + @args.omit_header end end diff --git a/spec-insert/lib/renderers/parameter_table_renderer.rb b/spec-insert/lib/renderers/parameter_table_renderer.rb index c23e90c240..23312962d8 100644 --- a/spec-insert/lib/renderers/parameter_table_renderer.rb +++ b/spec-insert/lib/renderers/parameter_table_renderer.rb @@ -11,7 +11,6 @@ def initialize(parameters, args) @pretty = args.pretty @parameters = parameters @parameters = @parameters.reject(&:deprecated) unless args.include_deprecated - @parameters += Parameter.global if args.include_global @parameters = @parameters.sort_by { |arg| [arg.required ? 0 : 1, arg.deprecated ? 1 : 0, arg.name] } end diff --git a/spec-insert/lib/renderers/path_parameters.rb b/spec-insert/lib/renderers/path_parameters.rb index 07476102f2..b1265bcf53 100644 --- a/spec-insert/lib/renderers/path_parameters.rb +++ b/spec-insert/lib/renderers/path_parameters.rb @@ -7,15 +7,8 @@ class PathParameters < BaseMustacheRenderer self.template_file = "#{__dir__}/templates/path_parameters.mustache" - # @param [Action] action API Action - # @param [InsertArguments] args - def initialize(action, args) - super(nil) - @params = action.arguments.select { |arg| arg.location == ArgLocation::PATH } - @args = args - end - def table - ParameterTableRenderer.new(@params, @args).render + params = @action.arguments.select { |arg| arg.location == ArgLocation::PATH } + ParameterTableRenderer.new(params, @args).render end end diff --git a/spec-insert/lib/renderers/paths_and_methods.rb b/spec-insert/lib/renderers/paths_and_methods.rb index f6776c8226..0685c03b36 100644 --- a/spec-insert/lib/renderers/paths_and_methods.rb +++ b/spec-insert/lib/renderers/paths_and_methods.rb @@ -6,12 +6,6 @@ class PathsAndMethods < BaseMustacheRenderer self.template_file = "#{__dir__}/templates/paths_and_methods.mustache" - # @param [Action] action API Action - def initialize(action) - super - @action = action - end - def operations ljust = @action.operations.map { |op| op.http_verb.length }.max @action.operations diff --git a/spec-insert/lib/renderers/query_parameters.rb b/spec-insert/lib/renderers/query_parameters.rb index 996a68903c..37058ba5f1 100644 --- a/spec-insert/lib/renderers/query_parameters.rb +++ b/spec-insert/lib/renderers/query_parameters.rb @@ -7,19 +7,9 @@ class QueryParameters < BaseMustacheRenderer self.template_file = "#{__dir__}/templates/query_parameters.mustache" - # @param [Action] action API Action - # @param [InsertArguments] args - def initialize(action, args) - super(nil) - @params = action.arguments.select { |arg| arg.location == ArgLocation::QUERY } - @args = args - end - def table - ParameterTableRenderer.new(@params, @args).render - end - - def optional - @params.none?(&:required) + params = @action.arguments.select { |arg| arg.location == ArgLocation::QUERY } + params += Parameter.global if @args.include_global + ParameterTableRenderer.new(params, @args).render end end diff --git a/spec-insert/lib/renderers/spec_insert.rb b/spec-insert/lib/renderers/spec_insert.rb index 4840b12e15..4d5ddb3803 100644 --- a/spec-insert/lib/renderers/spec_insert.rb +++ b/spec-insert/lib/renderers/spec_insert.rb @@ -15,9 +15,9 @@ class SpecInsert < BaseMustacheRenderer # @param [Array] arg_lines the lines between "" def initialize(arg_lines) - super - @args = InsertArguments.new(arg_lines) - @action = Action.actions[@args.api] + args = InsertArguments.new(arg_lines) + action = Action.actions[args.api] + super(action, args) raise SpecInsertError, '`api` argument not specified.' unless @args.api raise SpecInsertError, "API Action '#{@args.api}' does not exist in the spec." unless @action end @@ -34,7 +34,7 @@ def content when :path_parameters PathParameters.new(@action, @args).render when :paths_and_http_methods - PathsAndMethods.new(@action).render + PathsAndMethods.new(@action, @args).render else raise SpecInsertError, "Invalid component: #{@args.component}" end diff --git a/spec-insert/lib/renderers/templates/path_parameters.mustache b/spec-insert/lib/renderers/templates/path_parameters.mustache index 1b97bededd..9d9a2df9d4 100644 --- a/spec-insert/lib/renderers/templates/path_parameters.mustache +++ b/spec-insert/lib/renderers/templates/path_parameters.mustache @@ -1,2 +1,4 @@ +{{^omit_header}} ## Path parameters +{{/omit_header}} {{{table}}} \ No newline at end of file diff --git a/spec-insert/lib/renderers/templates/paths_and_methods.mustache b/spec-insert/lib/renderers/templates/paths_and_methods.mustache index 5221de6158..3c2df68011 100644 --- a/spec-insert/lib/renderers/templates/paths_and_methods.mustache +++ b/spec-insert/lib/renderers/templates/paths_and_methods.mustache @@ -1,4 +1,6 @@ +{{^omit_header}} ## Paths and HTTP methods +{{/omit_header}} ```json {{#operations}} {{{verb}}} {{{path}}} diff --git a/spec-insert/lib/renderers/templates/query_parameters.mustache b/spec-insert/lib/renderers/templates/query_parameters.mustache index 4ca8255180..d7331d8f5a 100644 --- a/spec-insert/lib/renderers/templates/query_parameters.mustache +++ b/spec-insert/lib/renderers/templates/query_parameters.mustache @@ -1,5 +1,7 @@ +{{^omit_header}} ## 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 48df5c2bd4..596f185458 100644 --- a/spec-insert/spec/_fixtures/expected_output/param_tables.md +++ b/spec-insert/spec/_fixtures/expected_output/param_tables.md @@ -34,8 +34,8 @@ Query Parameters Example with only Parameter and Description Columns api: search component: query_parameters columns: Parameter, Description +omit_header: true --> -## Query parameters 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. diff --git a/spec-insert/spec/_fixtures/input/param_tables.md b/spec-insert/spec/_fixtures/input/param_tables.md index e53c09026a..d9f24e23f9 100644 --- a/spec-insert/spec/_fixtures/input/param_tables.md +++ b/spec-insert/spec/_fixtures/input/param_tables.md @@ -29,6 +29,7 @@ Query Parameters Example with only Parameter and Description Columns api: search component: query_parameters columns: Parameter, Description +omit_header: true --> THIS TEXT