From 9beccb25f486da187e6c9c25aa7eb26c09d51842 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Fri, 22 Mar 2024 10:42:44 -0300 Subject: [PATCH] update specs based on feedback --- specs/cli/client-add.md | 2 +- specs/cli/plugin-add.md | 8 ++++---- specs/cli/plugin-edit.md | 6 +++--- specs/cli/plugin-generate.md | 2 +- specs/cli/plugin-remove.md | 2 +- specs/scenarios/plugins.md | 2 +- 6 files changed, 11 insertions(+), 11 deletions(-) diff --git a/specs/cli/client-add.md b/specs/cli/client-add.md index c960bb549c..87c28860ea 100644 --- a/specs/cli/client-add.md +++ b/specs/cli/client-add.md @@ -2,7 +2,7 @@ ## Description -`kiota client add` allows a developer to add a new API client to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory in current working directory. The command will add a new entry to the `clients` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/clients` folder. If a client with the same name already exists, the command will fail and display an actionable error message. +`kiota client add` allows a developer to add a new API client to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory in current working directory. The command will add a new entry to the `clients` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/clients` folder. If a client or plugin with the same name already exists, the command will fail and display an actionable error message. When executing, a new API entry will be added and will use the `--client-name` parameter as the key for the map. When loading the OpenAPI description, it will store the location of the description in the `descriptionLocation` property. If `--include-path` or `--exclude-path` are provided, they will be stored in the `includePatterns` and `excludePatterns` properties respectively. diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index f814fdda88..4fc97769c5 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -2,7 +2,7 @@ ## Description -`kiota plugin add` allows a developer to add a new plugin to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory under the current working directory. The command will add a new entry to the `plugins` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/plugins` folder. If a plugin with the same name already exists, the command will fail and display an actionable error message. +`kiota plugin add` allows a developer to add a new plugin to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory under the current working directory. The command will add a new entry to the `plugins` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/plugins` folder. If a plugin or client with the same name already exists, the command will fail and display an actionable error message. When executing, a new plugin entry will be added and will use the `--plugin-name` parameter as the key for the map. When loading the OpenAPI description, it will store the location of the description in the `descriptionLocation` property. If `--include-path` or `--exclude-path` are provided, they will be stored in the `includePatterns` and `excludePatterns` properties respectively. @@ -20,13 +20,13 @@ Once the `workspace.json` file is generated and the OpenAPI description file is | Parameters | Required | Example | Description | Telemetry | | -- | -- | -- | -- | -- | -| `--plugin-name \| --mn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | +| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | No | | `--search-key \| --sk` | No | apisguru::github.com:api.github.com | The search key used to locate the OpenAPI description. | Yes, without its value | | `--include-path \| -i` | No | /repos/{owner}/{repo} | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | | `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | | `--type \| -t` | Yes | openai | The target type of plugin for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| Yes | -| `--overlayDirectory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | +| `--overlay-directory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | | `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the location of `workspace.json`. Defaults to `./output`. | Yes, without its value | @@ -50,7 +50,7 @@ _The resulting `workspace.json` file will look like this:_ "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "includePatterns": ["/repos/{owner}/{repo}"], "excludePatterns": [], - "type": "openai", + "type": ["openai"], "outputDirectory": "./generated/plugins/github", "overlayDirectory": "./overlays/plugins/github/overlay.yaml" } diff --git a/specs/cli/plugin-edit.md b/specs/cli/plugin-edit.md index d36eb116c5..acfaab2ee8 100644 --- a/specs/cli/plugin-edit.md +++ b/specs/cli/plugin-edit.md @@ -14,12 +14,12 @@ Once the `workspace.json` file and the API Manifest are updated, the code genera | Parameters | Required | Example | Description | Telemetry | | -- | -- | -- | -- | -- | -| `--plugin-name \| --mn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | +| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | Yes, without its value | | `--include-path \| -i` | No | /repos/{owner}/{repo} | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | | `--exclude-path \| -e` | No | /repos/{owner}/{repo}#DELETE | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | | `--type \| -t` | Yes | openai | The target type of plugin for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| Yes | -| `--overlayDirectory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | +| `--overlay-directory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | | `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the current working directory. Defaults to `./output`. | Yes, without its value | @@ -43,7 +43,7 @@ _The resulting `workspace.json` file will look like this:_ "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "includePatterns": ["/repos/{owner}/{repo}"], "excludePatterns": ["/repos/{owner}/{repo}#DELETE"], - "type": "openai", + "type": ["openai"], "outputDirectory": "./generated/plugins/github", "overlayDirectory": "./overlays/plugins/github/overlay.yaml" } diff --git a/specs/cli/plugin-generate.md b/specs/cli/plugin-generate.md index 033f598658..31f58420c4 100644 --- a/specs/cli/plugin-generate.md +++ b/specs/cli/plugin-generate.md @@ -12,7 +12,7 @@ In general cases, the `kiota plugin generate` command will generate the output f | Parameters | Required | Example | Description | Telemetry | | -- | -- | -- | -- | -- | -| `--plugin-name \| --mn` | No | GitHub | Name of the plugin. Unique within the parent API. | Yes, without its value | +| `--plugin-name \| --pn` | No | GitHub | Name of the plugin. Unique within the parent API. | Yes, without its value | | `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. | Yes | ## Usage diff --git a/specs/cli/plugin-remove.md b/specs/cli/plugin-remove.md index c75f6cf5f3..1df6ba4b4b 100644 --- a/specs/cli/plugin-remove.md +++ b/specs/cli/plugin-remove.md @@ -8,7 +8,7 @@ The command also has one optional parameter, the ability to remove the all gener | Parameters | Required | Example | Description | Telemetry | | -- | -- | -- | -- | -- | -| `--plugin-name \| --mn` | Yes | GitHub | Name of the plugin | No | +| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin | No | | `--clean-output \| --co` | No | | Cleans the generated plugin files | Yes | #### Using kiota plugin remove and deleting all the content diff --git a/specs/scenarios/plugins.md b/specs/scenarios/plugins.md index e24391c3ff..2621f2be65 100644 --- a/specs/scenarios/plugins.md +++ b/specs/scenarios/plugins.md @@ -36,7 +36,7 @@ Here is an example of what the `workspace.json` file could look like. "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "includePatterns": ["/repos/{owner}/{repo}"], "excludePatterns": [], - "type": "openai", + "type": ["openai"], "outputDirectory": "./generated/plugins/github", "overlayDirectory": "./overlays/plugins/github/overlay.yaml" }