Specs/kiota plugin

specs/cli/client-add.md

@@ -2,13 +2,13 @@
 
 ## 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.
 
 Every time an API client is added, a copy of the OpenAPI description file will be stored in the `./.kiota/clients/{client-name}.yaml|json` folder. The files will be named using the API client name. This will allow the CLI to detect changes in the description and avoid downloading the description again if it hasn't changed. 
 
-At the same time, an [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html) file will be generated (if non existing) or edited (if already existing) in the `.kiota` folder next to `workspace.json`. API Manifest represents a snapshot of API dependencies and permissions required to access those APIs. This file will represent a concatenated surface of all APIs used across plugins and clients. Both files, `apimanifest.json` and `workspace.json` will be used to generate the code files. A new hash composed of the Kiota version, the OpenAPI description location and the properties of the manifest will be generated and would trigger an update to the [API Manifest][https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html].
+At the same time, an [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html) file will be generated (if non existing) or edited (if already existing) in the `.kiota` folder next to `workspace.json`. API Manifest represents a snapshot of API dependencies and permissions required to access those APIs. This file will represent a concatenated surface of all APIs used across plugins and clients. Both files, `apimanifest.json` and `workspace.json` will be used to generate the code files. A new hash composed of the Kiota version, the OpenAPI description location and the properties of the client will be generated and would trigger an update to the [API Manifest][https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html].
 
 Once the `workspace.json` file is generated and the OpenAPI description file is saved locally, the code generation will be executed and then the API Manifest would become available.
 

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.
 
@@ -16,17 +16,40 @@ Developers can generate `openai` and `apimanifest` type of plugins. By generatin
 
 Once the `workspace.json` file is generated and the OpenAPI description file is saved locally, the generation will be executed and the plugin and the sliced OpenAPI description will become available.
 
+For `openai` plugins, the mapping should follow [Hidi logic to generate OpenAI Plugin](https://github.com/microsoft/OpenAPI.NET/blob/vnext/src/Microsoft.OpenApi.Hidi/OpenApiService.cs#L748). Requiring fields default as the following:
+
+| OpenAI field | Default value |
+| -- | -- |
+| name_for_human | Defaults to the OpenAPI document title. |
+| name_for_model | Defaults to `{name_for_human}`. |
+| description_for_human | Defaults to the description from the OpenAPI document.  If the description is not available, it defaults to `Description for {name_for_human}`. |
+| description_for_model | Defaults to `{description_for_human}`. |
+| contact_email | Defaults to the contact email from the OpenAPI document. If the contact email is not available, it defaults to '[email protected]'. |
+| logo_url | Dummy URL? |
+| legal_info_url | Dummy URL? |
+|  |  |
+
+For `apimanifest`, the mapping should follow the [OpenApi.ApiManifest lib map](https://github.com/microsoft/OpenApi.ApiManifest/blob/main/docs/OpenApiToApiManifestMapping.md). Requiring fields are as the following:
+
+| API Manifest field | Default value |
+| -- | -- |
+| apiDependencies.Key | Defaults to the plugin name. |
+| publisherName | Defaults to the contact name from the OpenAPI document. If the contact name is not available, it defaults to 'publisher-name'. |
+| publisherName | Defaults to the contact name from the OpenAPI document. If the contact name is not available, it defaults to 'publisher-name'. |
+| publisherEmail | Defaults to the contact email from the OpenAPI document. If the contact email is not available, it defaults to '[email protected]'. |
+|  |  |
+
 ## Parameters
 
 | 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 +73,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"
     }

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"
     }

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

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

specs/cli/workspace-init.md

@@ -1,25 +1,25 @@
-# `kiota config init`
+# `kiota workspace init`
 
 ## Description
 
-`kiota config init` creates a new kiota-config.json file with the provided parameters. If the file already exists, it should error out and report it to the user. As the file gets created, it should be adding a `version` property with the value of the `kiota-config.json` current schema version. 
+`kiota workspace init` creates a new workspace.json file with the provided parameters. If the file already exists, it should error out and report it to the user. As the file gets created, it should be adding a `version` property with the value of the `workspace.json` current schema version. 
 
-When `kiota config init` is executed, a `kiota-config.json` file would be created in the current directory where the command is being executed. If the user wants to create the file in a different directory, they should use the `--config-file` global parameter.
+When `kiota workspace init` is executed, a `workspace.json` file would be created in the current directory where the command is being executed. If the user wants to create the file in a different directory, they should use the `--workspace-file` global parameter.
 
 > [!NOTE] 
-> If a project only needs a single API, using `kiota config init` is not mandatory as generating code using the `kiota client generate` or `kiota plugin generate` command could generate a `kiota-config.json` file with values coming from the `kiota client generate` or `kiota plugin generate` commands (if no `kiota-config.json` is present). See [kiota client generate](./client-generate.md) or [kiota plugin generate](./plugin-generate.md) for more information.
+> If a project only needs a single API, using `kiota workspace init` is not mandatory as generating code using the `kiota client generate` or `kiota plugin generate` command could generate a `workspace.json` file with values coming from the `kiota client generate` or `kiota plugin generate` commands (if no `workspace.json` is present). See [kiota client generate](./client-generate.md) or [kiota plugin generate](./plugin-generate.md) for more information.
 
 ## Parameters
 
 None.
 
-## Using `kiota config init`
+## Using `kiota workspace init`
 
 ```bash
-kiota config init
+kiota workspace init
 ```
 
-_The resulting `kiota-config.json` file will look like this:_
+_The resulting `workspace.json` file will look like this:_
 
 ```jsonc
 {
@@ -30,5 +30,6 @@ _The resulting `kiota-config.json` file will look like this:_
 ## File structure
 ```bash
 /
- └─kiota-config.json
+ └─.kiota
+    └─workspace.json
 ```