From aa814b7f862c5bc56284162509dc69afb4b7c6b6 Mon Sep 17 00:00:00 2001 From: Theo Truong Date: Sun, 6 Oct 2024 19:17:06 -0600 Subject: [PATCH 1/6] Spec Insert A program that insert API Components generated from the OpenSearch OpenAPI Spec into markdown files Signed-off-by: Theo Truong --- DEVELOPER_GUIDE.md | 85 +++++++++++++++++----------------------------- 1 file changed, 31 insertions(+), 54 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index f414fe0020..2a5ecf6e7a 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -1,32 +1,29 @@ -# Developer guide +# 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) + - [Using spec-insert Jekyll plugin](#using-spec-insert-jekyll-plugin) + - [Insert Query Parameters](#insert-query-parameters) + - [Insert Path Parameters](#insert-path-parameters) + - [Insert Paths and HTTP Methods](#insert-paths-and-http-methods) + - [Ignored files and folders](#ignored-files-and-folders) - [CI/CD](#cicd) ## Introduction - The `.md` documents in this repository are rendered into HTML pages using [Jekyll](https://jekyllrb.com/). These HTML pages are hosted on [opensearch.org](https://opensearch.org/docs/latest/). ## Starting the Jekyll server locally -You can run the Jekyll server locally to view the rendered HTML pages using the following steps: - -1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) 3.1.0 or later for your operating system. -2. Install the required gems by running `bundle install`. -3. Run `bundle exec jekyll serve` to start the Jekyll server locally (this can take several minutes to complete). -4. Open your browser and navigate to `http://localhost:4000` to view the rendered HTML pages. +You can run the Jekyll server locally to view the rendered HTML pages after making changes to the markdown files: +- Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) 3.1.0 or later for your operating system. +- Install the required gems by running `bundle install`. +- Run `bundle exec jekyll serve` to start the Jekyll server locally. (This can take several minutes to be ready.) +- Open your browser and navigate to `http://localhost:4000` to view the rendered HTML pages. -## Using the `spec-insert` Jekyll plugin -The `spec-insert` Jekyll plugin is used to insert API components into Markdown files. The plugin downloads the [latest OpenSearch specification](https://github.com/opensearch-project/opensearch-api-specification) and renders the API components from the spec. This aims to reduce the manual effort required to keep the documentation up to date. +## Using spec-insert Jekyll plugin +The `spec-insert` Jekyll plugin is used to insert API components into the markdown files. The plugin downloads the latest OpenSearch Specification and renders the API components from the spec. This aims to reduce the manual effort required to keep the documentation up-to-date. To use this plugin, make sure that you have installed Ruby 3.1.0 or later and the required gems by running `bundle install`. -Edit your Markdown file and insert the following snippet where you want render an API component: - +Edit your markdown file and insert the following snippet where you want an API component to be rendered: ```markdown ``` -Then run the following Jekyll command to render the API components: +Then run the follow Jekyll command to render the API components: ```shell bundle exec jekyll spec-insert ``` -If you are working on multiple Markdown files and do not want to keep running the `jekyll spec-insert` command, you can add the `--watch` (or `-W`) flag to the command to watch for changes in the Markdown files and automatically render the API components: - +If you are working on multiple markdown files and do not want to keep running the `jekyll spec-insert` command, you can add the `--watch` (or `-W`) flag to the command to watch for changes in the markdown files and automatically render the API components: ```shell bundle exec jekyll spec-insert --watch ``` -Depending on the text editor you are using, you may need to manually reload the file from disk to see the changes applied by the plugin if the editor does not automatically reload the file periodically. +Note that depending on the text editor you are using to edit the markdown, you may need to manually reload the file from disk to see the changes applied by the plugin if the editor does not automatically reload the file periodically. -The plugin will pull the newest OpenSearch API spec from its [repository](https://github.com/opensearch-project/opensearch-api-specification) if the spec file does not exist locally or if it is older than 24 hours. To tell the plugin to always pull the newest spec, you can add the `--refresh-spec` (or `-R`) flag to the command: +The plugin will pull the newest OpenSearch Spec from its [repository](https://github.com/opensearch-project/opensearch-api-specification) if the spec file does not exist locally or if it is older than 24 hours. To tell the plugin to always pull the newest spec, you can add the `--refresh-spec` (or `-R`) flag to the command: ```shell bundle exec jekyll spec-insert --refresh-spec ``` -### Inserting query parameters - -To insert the API query parameters table, use the following snippet: - +### Insert Query Parameters +To insert 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: - -- `Parameter` -- `Type` -- `Description` -- `Required` -- `Default` - - 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. - -The following snippet inserts the specified columns into the query parameters table: +- This will insert the query parameters of the `cat.indices` API into the markdown file 3 default columns: `Parameter`, `Type`, and `Description`. There are 5 columns that can be inserted: `Parameter`, `Type`, `Description`, `Required`, and `Default`. When `Required`/`Default` is not chosen, the info will be written in the `Description` column. +- This component accepts `include_global` (boolean, default to `false`) argument to include global query parameters in the table. +- This component accepts `include_deprecated` (boolean, default to `true`) argument to include deprecated parameters in the table. +- This component accepts `pretty` (boolean, default to `false`) argument to render the table in the pretty format instead of the compact format. ```markdown ``` -### Inserting path parameters - -To insert the `indices.create` API path parameters table, use the following snippet: +### Insert Path Parameters +To insert path parameters table of the `indices.create` API, use the following snippet: ```markdown ``` -This table behaves identically to the query parameters table except that it does not accept the `include_global` argument. +This table behaves the same as the query parameters table except that it does not accept the `include_global` argument. -### Inserting paths and HTTP methods - -To insert paths and HTTP methods for the `search` API, use the following snippet: +### Insert Paths and HTTP Methods +To insert paths and HTTP methods of the `search` API, use the following snippet: ```markdown ``` -### Ignoring files and folders - +### Ignored 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. +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 done through the [update-api-components.yml](.github/workflows/update-api-components.yml) Github Action workflow that creates a pull request with the updated API components every Monday. \ No newline at end of file From cfb2ebceb5ef0362b7281b50e40a7c687ce81a4b Mon Sep 17 00:00:00 2001 From: Theo Truong Date: Thu, 7 Nov 2024 14:44:26 -0700 Subject: [PATCH 2/6] # vale:reviewdog Signed-off-by: Theo Truong --- DEVELOPER_GUIDE.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 2a5ecf6e7a..dedbeaf632 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -55,7 +55,7 @@ The plugin will pull the newest OpenSearch Spec from its [repository](https://gi bundle exec jekyll spec-insert --refresh-spec ``` -### Insert Query Parameters +### Insert query parameters To insert query parameters table of the `cat.indices` API, use the following snippet: ```markdown ``` -### Insert Path Parameters +### Insert path parameters To insert path parameters table of the `indices.create` API, use the following snippet: ```markdown @@ -94,7 +94,7 @@ component: path_parameters This table behaves the same as the query parameters table except that it does not accept the `include_global` argument. -### Insert Paths and HTTP Methods +### Insert paths and HTTP methods To insert paths and HTTP methods of the `search` API, use the following snippet: ```markdown @@ -109,4 +109,4 @@ component: paths_and_http_methods 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 done through the [update-api-components.yml](.github/workflows/update-api-components.yml) Github Action workflow that creates a pull request with the updated API components every Monday. \ No newline at end of file +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 done through the [update-api-components.yml](.github/workflows/update-api-components.yml) GitHub Action workflow that creates a pull request with the updated API components every Monday. \ No newline at end of file From fe2f23b1c59b38de7b6ecc2ecf1323e5e6b7673d Mon Sep 17 00:00:00 2001 From: Theo Truong Date: Thu, 7 Nov 2024 14:54:12 -0700 Subject: [PATCH 3/6] # Correction on cron job run time. 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 dedbeaf632..063beb773e 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -109,4 +109,4 @@ component: paths_and_http_methods 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 done through the [update-api-components.yml](.github/workflows/update-api-components.yml) GitHub Action workflow that creates a pull request with the updated API components every Monday. \ No newline at end of file +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 done through the [update-api-components.yml](.github/workflows/update-api-components.yml) GitHub Action workflow that creates a pull request with the updated API components every Sunday. \ No newline at end of file From f8926c0086308d8172c907259ad15f18a73f0dc3 Mon Sep 17 00:00:00 2001 From: "Theo N. Truong" Date: Fri, 8 Nov 2024 10:09:06 -0700 Subject: [PATCH 4/6] 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 --- DEVELOPER_GUIDE.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 063beb773e..2bf75d6df2 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -1,4 +1,4 @@ -# Developer Guide +# Developer guide - [Introduction](#introduction) - [Starting the Jekyll server locally](#starting-the-jekyll-server-locally) - [Using spec-insert Jekyll plugin](#using-spec-insert-jekyll-plugin) @@ -19,7 +19,7 @@ You can run the Jekyll server locally to view the rendered HTML pages after maki - Open your browser and navigate to `http://localhost:4000` to view the rendered HTML pages. ## Using spec-insert Jekyll plugin -The `spec-insert` Jekyll plugin is used to insert API components into the markdown files. The plugin downloads the latest OpenSearch Specification and renders the API components from the spec. This aims to reduce the manual effort required to keep the documentation up-to-date. +The `spec-insert` Jekyll plugin is used to insert API components into the markdown files. The plugin downloads the [latest OpenSearch Specification](https://github.com/opensearch-project/opensearch-api-specification) and renders the API components from the spec. This aims to reduce the manual effort required to keep the documentation up-to-date. To use this plugin, make sure that you have installed Ruby 3.1.0 or later and the required gems by running `bundle install`. @@ -55,7 +55,7 @@ The plugin will pull the newest OpenSearch Spec from its [repository](https://gi bundle exec jekyll spec-insert --refresh-spec ``` -### Insert query parameters +### Inserting query parameters To insert query parameters table of the `cat.indices` API, use the following snippet: ```markdown ``` -### Insert path parameters +### Inserting path parameters To insert path parameters table of the `indices.create` API, use the following snippet: ```markdown @@ -94,7 +94,7 @@ component: path_parameters This table behaves the same as the query parameters table except that it does not accept the `include_global` argument. -### Insert paths and HTTP methods +### Inserting paths and HTTP methods To insert paths and HTTP methods of the `search` API, use the following snippet: ```markdown @@ -105,7 +105,7 @@ component: paths_and_http_methods ``` -### Ignored files and folders +### 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 From 9970cea38459a19d74b2ccdf1c035339e8e6f911 Mon Sep 17 00:00:00 2001 From: Theo Truong Date: Fri, 15 Nov 2024 09:39:53 -0700 Subject: [PATCH 5/6] Added `omit_header` argument for Spec Insert components (Some minor refactoring to DRY the code as well) Signed-off-by: Theo Truong --- DEVELOPER_GUIDE.md | 101 +++++++++++------- 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, 91 insertions(+), 80 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 2bf75d6df2..9e7c9aeaf1 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -1,34 +1,38 @@ # Developer guide - - [Introduction](#introduction) - - [Starting the Jekyll server locally](#starting-the-jekyll-server-locally) - - [Using spec-insert Jekyll plugin](#using-spec-insert-jekyll-plugin) - - [Insert Query Parameters](#insert-query-parameters) - - [Insert Path Parameters](#insert-path-parameters) - - [Insert Paths and HTTP Methods](#insert-paths-and-http-methods) - - [Ignored files and folders](#ignored-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 + The `.md` documents in this repository are rendered into HTML pages using [Jekyll](https://jekyllrb.com/). These HTML pages are hosted on [opensearch.org](https://opensearch.org/docs/latest/). ## Starting the Jekyll server locally -You can run the Jekyll server locally to view the rendered HTML pages after making changes to the markdown files: -- Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) 3.1.0 or later for your operating system. -- Install the required gems by running `bundle install`. -- Run `bundle exec jekyll serve` to start the Jekyll server locally. (This can take several minutes to be ready.) -- Open your browser and navigate to `http://localhost:4000` to view the rendered HTML pages. +You can run the Jekyll server locally to view the rendered HTML pages using the following steps: + +1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) 3.1.0 or later for your operating system. +2. Install the required gems by running `bundle install`. +3. Run `bundle exec jekyll serve` to start the Jekyll server locally (this can take several minutes to complete). +4. Open your browser and navigate to `http://localhost:4000` to view the rendered HTML pages. -## Using spec-insert Jekyll plugin -The `spec-insert` Jekyll plugin is used to insert API components into the markdown files. The plugin downloads the [latest OpenSearch Specification](https://github.com/opensearch-project/opensearch-api-specification) and renders the API components from the spec. This aims to reduce the manual effort required to keep the documentation up-to-date. +## Using the `spec-insert` Jekyll plugin +The `spec-insert` Jekyll plugin is used to insert API components into Markdown files. The plugin downloads the [latest OpenSearch specification](https://github.com/opensearch-project/opensearch-api-specification) and renders the API components from the spec. This aims to reduce the manual effort required to keep the documentation up to date. To use this plugin, make sure that you have installed Ruby 3.1.0 or later and the required gems by running `bundle install`. -Edit your markdown file and insert the following snippet where you want an API component to be rendered: +Edit your Markdown file and insert the following snippet where you want render an API component: + ```markdown This is where the API component will be inserted. @@ -37,26 +41,39 @@ Everything between the `spec_insert_start` and `spec_insert_end` tags will be ov ``` -Then run the follow Jekyll command to render the API components: +Then run the following Jekyll command to render the API components: ```shell bundle exec jekyll spec-insert ``` -If you are working on multiple markdown files and do not want to keep running the `jekyll spec-insert` command, you can add the `--watch` (or `-W`) flag to the command to watch for changes in the markdown files and automatically render the API components: +If you are working on multiple Markdown files and do not want to keep running the `jekyll spec-insert` command, you can add the `--watch` (or `-W`) flag to the command to watch for changes in the Markdown files and automatically render the API components: + ```shell bundle exec jekyll spec-insert --watch ``` -Note that depending on the text editor you are using to edit the markdown, you may need to manually reload the file from disk to see the changes applied by the plugin if the editor does not automatically reload the file periodically. +Depending on the text editor you are using, you may need to manually reload the file from disk to see the changes applied by the plugin if the editor does not automatically reload the file periodically. -The plugin will pull the newest OpenSearch Spec from its [repository](https://github.com/opensearch-project/opensearch-api-specification) if the spec file does not exist locally or if it is older than 24 hours. To tell the plugin to always pull the newest spec, you can add the `--refresh-spec` (or `-R`) flag to the command: +The plugin will pull the newest OpenSearch API spec from its [repository](https://github.com/opensearch-project/opensearch-api-specification) if the spec file does not exist locally or if it is older than 24 hours. To tell the plugin to always pull the newest spec, you can add the `--refresh-spec` (or `-R`) flag to the command: ```shell bundle exec jekyll spec-insert --refresh-spec ``` -### Inserting query parameters -To insert query parameters table of the `cat.indices` API, use the following snippet: +### 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. + +## 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 (e.g., `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 (e.g. `## Query parameters`) 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 markdown file 3 default columns: `Parameter`, `Type`, and `Description`. There are 5 columns that can be inserted: `Parameter`, `Type`, `Description`, `Required`, and `Default`. When `Required`/`Default` is not chosen, the info will be written in the `Description` column. -- This component accepts `include_global` (Boolean, default to `false`) argument to include global query parameters in the table. -- This component accepts `include_deprecated` (Boolean, default to `true`) argument to include deprecated parameters in the table. -- This component accepts `pretty` (Boolean, default to `false`) argument to render the table in the pretty format instead of the compact format. +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` +- `Default` + +_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. + +The following snippet inserts the specified columns into the query parameters table: ```markdown ``` -### Inserting path parameters - +### 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. -### Inserting paths and HTTP methods - -To insert paths and HTTP methods of the `search` API, use the following snippet: +### 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 done through the [update-api-components.yml](.github/workflows/update-api-components.yml) GitHub Action workflow that creates a pull request with the updated API components every Sunday. \ No newline at end of file +``` \ 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 From c5708917197c2a821a8778f9e3035c310f1547f7 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Fri, 15 Nov 2024 11:27:23 -0600 Subject: [PATCH 6/6] Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- DEVELOPER_GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 9e7c9aeaf1..18de000473 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -69,8 +69,8 @@ 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 (e.g., `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 (e.g. `## Query parameters`) will not be rendered. +- `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: