diff --git a/.vscode/settings.json b/.vscode/settings.json index 710961fd44..830dcc59fb 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -22,6 +22,7 @@ ], "cSpell.words": [ "allof", + "apimanifest", "apisguru", "autoload", "Contoso", diff --git a/specs/cli/client-add.md b/specs/cli/client-add.md index c03d727c0a..90e80a6b22 100644 --- a/specs/cli/client-add.md +++ b/specs/cli/client-add.md @@ -2,15 +2,15 @@ ## Description -`kiota client add` allows a developer to add a new API client to the `kiota-config.json` file. If no `kiota-config.json` file is found, a new `kiota-config.json` file would be created in the current working directory. The command will add a new entry to the `clients` section of the `kiota-config.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 actionnable 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 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 root folder next to `kiota-config.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 `kiota-config.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 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]. -Once the `kiota-config.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. +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. ## Parameters @@ -27,10 +27,10 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file | `--exclude-backward-compatible \| --ebc` | No | | Whether to exclude the code generated only for backward compatibility reasons or not. Defaults to `false`. | Yes | | `--structured-media-types \| -m` | No | `application/json` | Any valid media type which will match a request body type or a response type in the OpenAPI description. Default are documented [here](https://learn.microsoft.com/en-us/openapi/kiota/using#--structured-mime-types--m). | Yes | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. |Yes | -| `--output \| -o` | No | ./generated/graph/csharp | The output directory or file path for the generated code files. This is relative to the location of `kiota-config.json`. Defaults to `./output`. | Yes, without its value | +| `--output \| -o` | No | ./generated/graph/csharp | The output directory or file path for the generated code files. This is relative to the location of `workspace.json`. Defaults to `./output`. | Yes, without its value | > [!NOTE] -> It is not required to use the CLI to add new clients. It is possible to add a new client by adding a new entry in the `clients` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json) for more information. Using `kiota client generate --client-name myClient` would be required to generate the code files. +> It is not required to use the CLI to add new clients. It is possible to add a new client by adding a new entry in the `clients` section of the `workspace.json` file. See the [workspace.json schema](../schemas/workspace.json) for more information. Using `kiota client generate --client-name myClient` would be required to generate the code files. ## Telemetry @@ -40,7 +40,7 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file kiota client add --client-name "GraphClient" --openapi "https://aka.ms/graph/v1.0/openapi.yaml" --include-path "**/users/**" --language csharp --namespace-name "Contoso.GraphApp" --backing-store --exclude-backward-compatible --serializer "Contoso.Json.CustomSerializer" --deserializer "Contoso.Json.CustomDeserializer" -structured-mime-types "application/json" --output "./generated/graph/csharp" ``` -_The resulting `kiota-config.json` file will look like this:_ +_The resulting `workspace.json` file will look like this:_ ```jsonc { @@ -105,16 +105,18 @@ _The resulting `apimanifest.json` file will look like this:_ ``` ## File structure + ```bash / └─.kiota └─clients - └─GraphClient.yaml + └─GraphClient + └─description.yaml + └─apimanifest.json + └─workspace.json └─generated └─graph └─csharp └─... # Generated code files └─GraphClient.cs - └─apimanifest.json - └─kiota-config.json -``` \ No newline at end of file +``` diff --git a/specs/cli/client-edit.md b/specs/cli/client-edit.md index eb8d70cfee..8e533ff474 100644 --- a/specs/cli/client-edit.md +++ b/specs/cli/client-edit.md @@ -2,11 +2,11 @@ ## Description -`kiota client update` allows a developer to edit an existing API client int the `kiota-config.json` file. If either the `kiota-config.json` file or if the `--client-name` client can't be found within the `kiota-config.json` file, the command should error out and let the developer know. +`kiota client update` allows a developer to edit an existing API client int the `workspace.json` file. If either the `workspace.json` file or if the `--client-name` client can't be found within the `workspace.json` file, the command should error out and let the developer know. -When executing, the API entry defined by the `--client-name` parameter will be modified. All parameters should be supported and the only required one is `--client-name`. All others are optional as they would only modify the configuration of the API client. If the OpenAPI description location changed or any properties of the client entry in `kiota-config.json`, a new hash composed of the Kiota version, the OpenAPI description location and the properties of the client will be generated and and would trigger an update to the [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html). +When executing, the API entry defined by the `--client-name` parameter will be modified. All parameters should be supported and the only required one is `--client-name`. All others are optional as they would only modify the configuration of the API client. If the OpenAPI description location changed or any properties of the client entry in `workspace.json`, a new hash composed of the Kiota version, the OpenAPI description location and the properties of the client will be generated and and would trigger an update to the [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html). -Once the `kiota-config.json` file and the API Manifest are updated, the code generation will be executed based on the newly updated API client configuration. +Once the `workspace.json` file and the API Manifest are updated, the code generation will be executed based on the newly updated API client configuration. ## Parameters @@ -25,7 +25,7 @@ Once the `kiota-config.json` file and the API Manifest are updated, the code gen | `--output \| -o` | No | ./generated/graph/csharp | The output directory or file path for the generated code files. Defaults to `./output`. | Yes, without its value | > [!NOTE] -> It is not required to use the CLI to edit clients. It is possible to edit a client by modifying its entry in the `clients` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json.md) for more information. +> It is not required to use the CLI to edit clients. It is possible to edit a client by modifying its entry in the `clients` section of the `workspace.json` file. See the [workspace.json schema](../schemas/workspace.json) for more information. ## Using `kiota client edit` @@ -33,7 +33,7 @@ Once the `kiota-config.json` file and the API Manifest are updated, the code gen kiota client edit --client-name "GraphClient" --exclude-path "/users/$count" ``` -_The resulting `kiota-config.json` file will look like this:_ +_The resulting `workspace.json` file will look like this:_ ```jsonc { @@ -102,12 +102,13 @@ _The resulting `apimanifest.json` file will look like this:_ / └─.kiota └─clients - └─GraphClient.yaml + └─GraphClient + └─description.yaml + └─apimanifest.json + └─workspace.json └─generated └─graph └─csharp └─... # Generated code files └─GraphClient.cs - └─apimanifest.json - └─kiota-config.json -``` \ No newline at end of file +``` diff --git a/specs/cli/client-generate.md b/specs/cli/client-generate.md index 84b93c1705..f59d40a59e 100644 --- a/specs/cli/client-generate.md +++ b/specs/cli/client-generate.md @@ -2,11 +2,11 @@ ## Description -Now that we have a `kiota-config.json` file, all the parameters required to generate the code are stored in the file. The `kiota client generate` command will read the `kiota-config.json` file and generate the code for each of the available clients. +Now that we have a `workspace.json` file, all the parameters required to generate the code are stored in the file. The `kiota client generate` command will read the `workspace.json` file and generate the code for each of the available clients. -It's also possible to specify for which API and client the code should be generated. This is useful when a project contains multiple clients. The `kiota client generate --client-name "MyClient"` command will read the `kiota-config.json` file and generate the code for the specified client. If it can't find the specified API or client, it will throw an error. +It's also possible to specify for which API and client the code should be generated. This is useful when a project contains multiple clients. The `kiota client generate --client-name "MyClient"` command will read the `workspace.json` file and generate the code for the specified client. If it can't find the specified API or client, it will throw an error. -In general cases, the `kiota client generate` command will generate the code for all the clients in the `kiota-config.json` file based on the cached OpenAPI description. If the `--refresh` parameter is provided, the command will refresh the cached OpenAPI description(s), update the different `x-ms-kiotaHash` in the API Manifest and then generate the code for the specified clients. +In general cases, the `kiota client generate` command will generate the code for all the clients in the `workspace.json` file based on the cached OpenAPI description. If the `--refresh` parameter is provided, the command will refresh the cached OpenAPI description(s), update the different `x-ms-kiotaHash` in the API Manifest and then generate the code for the specified clients. ## Parameters diff --git a/specs/cli/client-remove.md b/specs/cli/client-remove.md index 4ce0465b29..9bc54757e1 100644 --- a/specs/cli/client-remove.md +++ b/specs/cli/client-remove.md @@ -2,7 +2,7 @@ ## Description -`kiota client remove` allows a developer to remove an existing client from the `kiota-config.json` file. The command will remove the entry from the `clients` section of `kiota-config.json` file. The command has a single required parameters; the name of the client. +`kiota client remove` allows a developer to remove an existing client from the `workspace.json` file. The command will remove the entry from the `clients` section of `workspace.json` file. The command has a single required parameters; the name of the client. The command also has one optional parameter, the ability to remove the generated client. If provided, kiota will delete the folder and its content specified at the `outputPath` from the client configuration. It will also remove the local version of the OpenAPI description file (specified by the `x-ms-kiotaHash` property in the API Manifest). The API Manifest is also updated to remove the dependency from the list of dependencies. @@ -17,7 +17,7 @@ The command also has one optional parameter, the ability to remove the generated kiota client remove --client-name "GraphClient" --clean-output ``` -The resulting `kiota-config.json` file will look like this: +The resulting `workspace.json` file will look like this: ```jsonc { @@ -38,8 +38,8 @@ _The resulting `apimanifest.json` file will look like this:_ ```bash / └─.kiota + └─workspace.json + └─apimanifest.json └─generated └─graph - └─kiota-config.json - └─apimanifest.json -``` \ No newline at end of file +``` diff --git a/specs/cli/index.md b/specs/cli/index.md index 413bc0932a..8ba13cb5dc 100644 --- a/specs/cli/index.md +++ b/specs/cli/index.md @@ -6,8 +6,8 @@ This section contains the specifications for the Kiota CLI commands. All the com * [kiota client edit](./client-edit.md) * [kiota client remove](./client-remove.md) * [kiota client generate](./client-generate.md) -* [kiota config init](./config-init.md) -* [kiota config migrate](./config-migrate.md) +* [kiota workspace init](./workspace-init.md) +* [kiota workspace migrate](./workspace-migrate.md) * [kiota download](./download.md) * [kiota info](./info.md) * [kiota login](./login.md) diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index ea7fef3b62..f814fdda88 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -2,19 +2,19 @@ ## Description -`kiota plugin add` allows a developer to add a new plugin to the `kiota-config.json` file. If no `kiota-config.json` file is found, a new `kiota-config.json` file would be created in the current working directory. The command will add a new entry to the `plugins` section of the `kiota-config.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 actionnable 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 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. Every time a plugin is added, a copy of the OpenAPI description file will be stored in the `./.kiota/plugins` folder. The OpenAPI will be named using the plugin name `{plugin-name}.json|yaml`. This will allow the CLI to detect changes in the description and avoid downloading the description again if it hasn't changed. -An [API Manifest][def] file named `apimanifest.json` will be generated (if non existing) or updated (if already existing) in the root folder `./kiota` next to `kiota-config.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 `kiota-config.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][def]. +An [API Manifest][def] file named `apimanifest.json` will be generated (if non existing) or updated (if already existing) in the root folder `./kiota` 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][def]. -Developers can generate `openai` and `apimanifest` type of plugins. By generating `openai` or `apimanifest`, two outputs will be generated: a\) the plugin type you have choosen that will be named `{plugin-name}-{type}.json` and b\) a sliced OpenAPI description with only the endpoints that matches `--include-path` and `--exclude-path`, if provided. +Developers can generate `openai` and `apimanifest` type of plugins. By generating `openai` or `apimanifest`, two outputs will be generated: a\) the plugin type you have chosen that will be named `{plugin-name}-{type}.json` and b\) a sliced OpenAPI description with only the endpoints that matches `--include-path` and `--exclude-path`, if provided. > [!NOTE] -> In one's solution, there might be two different [API Manifests][def]. The `apimanifest.json` in the root folder represents a single artifact surface of all APIs and it will always be generated. The second one, specific to each plugin, will be named `{plugin-name}-apimanifest.json` and saved in the choosen output directory when `apimanifest` value is used as the plugin type. +> In one's solution, there might be two different [API Manifests][def]. The `apimanifest.json` in the root folder represents a single artifact surface of all APIs and it will always be generated. The second one, specific to each plugin, will be named `{plugin-name}-apimanifest.json` and saved in the chosen output directory when `apimanifest` value is used as the plugin type. -Once the `kiota-config.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. +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. ## Parameters @@ -28,10 +28,10 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file | `--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 | | `--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 `kiota-config.json`. Defaults to `./output`. | Yes, without its value | +| `--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 | > [!NOTE] -> It is not required to use the CLI to add new plugins. It is possible to add a new plugin by adding a new entry in the `plugins` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json) for more information. Using `kiota plugin generate --plugin-name myPlugin` would be required to generate the plugins. +> It is not required to use the CLI to add new plugins. It is possible to add a new plugin by adding a new entry in the `plugins` section of the `workspace.json` file. See the [workspace.json schema](../schemas/workspace.json) for more information. Using `kiota plugin generate --plugin-name myPlugin` would be required to generate the plugins. ## Using `kiota plugin add` @@ -39,7 +39,7 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file kiota plugin add --plugins-name "GitHub" --openapi "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json" --include-path "/repos/{owner}/{repo}" --type openai, apimanifest --output "./generated/plugins/github" ``` -_The resulting `kiota-config.json` file will look like this:_ +_The resulting `workspace.json` file will look like this:_ ```jsonc { @@ -148,6 +148,8 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs depende ## File structure ```bash └─.kiota + └─workspace.json + └─apimanifest.json # Single artifact with all APIs dependencies info └─plugins └─GitHub.json # OpenAPI description └─generated @@ -156,8 +158,6 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs depende └─github-apimanifest.json # Specific API Manifest └─github-openai.json #OpenAI Plugin └─sliced-openapi-github.json # Sliced OpenAPI description - └─kiota-config.json - └─apimanifest.json # Single artifact with all APIs dependencies info ``` [def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html \ No newline at end of file diff --git a/specs/cli/plugin-edit.md b/specs/cli/plugin-edit.md index 6d97e96291..d36eb116c5 100644 --- a/specs/cli/plugin-edit.md +++ b/specs/cli/plugin-edit.md @@ -2,13 +2,13 @@ ## Description -`kiota plugin update` allows a developer to edit an existing plugin in the `kiota-config.json` file. If either the `kiota-config.json` file or if the `--plugin-name` plugin can't be found within the `kiota-config.json` file, the command should error out and let the developer know. +`kiota plugin update` allows a developer to edit an existing plugin in the `workspace.json` file. If either the `workspace.json` file or if the `--plugin-name` plugin can't be found within the `workspace.json` file, the command should error out and let the developer know. -When executing, the plugin entry defined by the `--plugin-name` parameter will be modified. All parameters should be supported and the only required one is `--plugin-name`. All others are optional as they would only modify the configuration of the plugin. If the OpenAPI description location changed or any properties of the plugin entry in `kiota-config.json`, a new hash composed of the Kiota version, the OpenAPI description location and the properties of the manifest will be generated and and would trigger an update to the [API Manifest][def] located in the root folder (the). +When executing, the plugin entry defined by the `--plugin-name` parameter will be modified. All parameters should be supported and the only required one is `--plugin-name`. All others are optional as they would only modify the configuration of the plugin. If the OpenAPI description location changed or any properties of the plugin entry in `workspace.json`, a new hash composed of the Kiota version, the OpenAPI description location and the properties of the manifest will be generated and and would trigger an update to the [API Manifest][def] located in the root folder (the). > [!NOTE] > > In one's solution, there might be two different [API Manifests][def]. The `apimanifest.json` in the root folder represents a single artifact surface of all APIs and it will always be generated. The second one, specific to each plugin, will be named `{plugin-name}-apimanifest.json` and saved in the choosen output directory when `apimanifest` value is used as the plugin type. -Once the `kiota-config.json` file and the API Manifest are updated, the code generation will be executed based on the newly updated API client configuration. +Once the `workspace.json` file and the API Manifest are updated, the code generation will be executed based on the newly updated API client configuration. ## Parameters @@ -21,10 +21,10 @@ Once the `kiota-config.json` file and the API Manifest are updated, the code gen | `--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 | | `--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 `kiota-config.json`. Defaults to `./output`. | Yes, without its value | +| `--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 | > [!NOTE] -> It is not required to use the CLI to edit plugins. It is possible to edit a plugin by modifying its entry in the `plugins` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json) for more information. +> It is not required to use the CLI to edit plugins. It is possible to edit a plugin by modifying its entry in the `plugins` section of the `workspace.json` file. See the [workspace.json schema](../schemas/workspace.json) for more information. ## Using `kiota plugin edit` @@ -32,7 +32,7 @@ Once the `kiota-config.json` file and the API Manifest are updated, the code gen kiota plugin edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}#DELETE" ``` -_The resulting `kiota-config.json` file will look like this:_ +_The resulting `workspace.json` file will look like this:_ ```jsonc { @@ -133,6 +133,8 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l ## File structure ```bash └─.kiota + └─workspace.json + └─apimanifest.json └─plugins └─GitHub.json # OpenAPI description └─generated @@ -141,8 +143,6 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l └─github-apimanifest.json # Specific API Manifest └─github-openai.json #OpenAI Plugin └─sliced-openapi-github.json # Sliced OpenAPI description - └─kiota-config.json - └─apimanifest.json ``` [def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html \ No newline at end of file diff --git a/specs/cli/plugin-generate.md b/specs/cli/plugin-generate.md index 7b7e553dc5..033f598658 100644 --- a/specs/cli/plugin-generate.md +++ b/specs/cli/plugin-generate.md @@ -2,11 +2,11 @@ ## Description -Now that we have a `kiota-config.json` file, all the parameters required to generate the plugins are stored in the file. The `kiota plugin generate` command will read the `kiota-config.json` file and generate the output files for each of the available plugins. +Now that we have a `workspace.json` file, all the parameters required to generate the plugins are stored in the file. The `kiota plugin generate` command will read the `workspace.json` file and generate the output files for each of the available plugins. -It's also possible to specify for which plugin the output files should be generated. This is useful when there are multiple plugin plugins. The `kiota plugin generate --plugin-name "Myplugin"` command will read the `kiota-config.json` file and generate the output files for the specified plugin. If it can't find the specified plugin, it will throw an error. +It's also possible to specify for which plugin the output files should be generated. This is useful when there are multiple plugin plugins. The `kiota plugin generate --plugin-name "Myplugin"` command will read the `workspace.json` file and generate the output files for the specified plugin. If it can't find the specified plugin, it will throw an error. -In general cases, the `kiota plugin generate` command will generate the output files for all the plugins in the `kiota-config.json` file based on the cached OpenAPI description. If the `--refresh` parameter is provided, the command will refresh the cached OpenAPI description(s), update the different `x-ms-kiotaHash` in the API plugins and then generate the output files for the specified plugins. +In general cases, the `kiota plugin generate` command will generate the output files for all the plugins in the `workspace.json` file based on the cached OpenAPI description. If the `--refresh` parameter is provided, the command will refresh the cached OpenAPI description(s), update the different `x-ms-kiotaHash` in the API plugins and then generate the output files for the specified plugins. ## Parameters diff --git a/specs/cli/plugin-remove.md b/specs/cli/plugin-remove.md index e159dcaa11..c75f6cf5f3 100644 --- a/specs/cli/plugin-remove.md +++ b/specs/cli/plugin-remove.md @@ -2,7 +2,7 @@ ## Description -`kiota plugin remove` allows a developer to remove an existing plugin from the `kiota-config.json` file. The command will remove the entry from the `plugins` section of `kiota-config.json` file. The command has a single required parameters; the name of the plugin. +`kiota plugin remove` allows a developer to remove an existing plugin from the `workspace.json` file. The command will remove the entry from the `plugins` section of `workspace.json` file. The command has a single required parameters; the name of the plugin. The command also has one optional parameter, the ability to remove the all generated files. If provided, kiota will delete the folder and its content specified at the `outputPath` from the plugin configuration. It will also remove the local version of the OpenAPI description file (specified by the `x-ms-kiotaHash` property in the API plugins). The API plugins are also updated to remove the dependency from the list of dependencies. @@ -18,7 +18,7 @@ kiota plugin remove --plugin-name "GitHub" --clean-output ``` _The resulting `github-apiplugin.json` and `github-openai.json` files will be deleted._ -The resulting `kiota-config.json` file will look like this: +The resulting `workspace.json` file will look like this: ```jsonc { @@ -47,9 +47,9 @@ _The resulting `apiplugin.json` file (concatenated surface of all APIs) will loo ```bash / └─.kiota + └─workspace.json └─generated └─plugins └─github - └─kiota-config.json └─apiplugin.json ``` \ No newline at end of file diff --git a/specs/cli/config-init.md b/specs/cli/workspace-init.md similarity index 100% rename from specs/cli/config-init.md rename to specs/cli/workspace-init.md diff --git a/specs/cli/config-migrate.md b/specs/cli/workspace-migrate.md similarity index 91% rename from specs/cli/config-migrate.md rename to specs/cli/workspace-migrate.md index ddab8f8d2a..24aa516f69 100644 --- a/specs/cli/config-migrate.md +++ b/specs/cli/workspace-migrate.md @@ -1,6 +1,6 @@ -# `kiota config migrate` +# `kiota workspace migrate` -This command is valuable in cases where a code base was created with Kiota v1.0 and needs to be migrated to the latest version of Kiota. The `kiota config migrate` command will identify and locate the closest `kiota-config.json` file available. If a file can't be found, it would initialize a new `kiota-config.json` file. Then, it would identify all `kiota-lock.json` files that are within this folder structure and add each of them to the `kiota-config.json` file. Adding the clients to the `kiota-config.json` file would not trigger the generation as it only affects the `kiota-config.json` file. The `kiota client generate` command would need to be executed to generate the code for the clients. +This command is valuable in cases where a code base was created with Kiota v1.0 and needs to be migrated to the latest version of Kiota. The `kiota config migrate` command will identify and locate the closest `workspace.json` file available. If a file can't be found, it would initialize a new `workspace.json` file. Then, it would identify all `kiota-lock.json` files that are within this folder structure and add each of them to the `workspace.json` file. Adding the clients to the `workspace.json` file would not trigger the generation as it only affects the `workspace.json` file. The `kiota client generate` command would need to be executed to generate the code for the clients. The API manifest won't contain any request after the migration since it could lead to misalignments between the generated client and the reported requests if the description has changed between the initial generation of the client and the migration. To get the requests populated, the user will need to use the generate command. diff --git a/specs/index.md b/specs/index.md index 8c4afc475a..9ef2c1f206 100644 --- a/specs/index.md +++ b/specs/index.md @@ -8,8 +8,8 @@ This repository contains the specifications for the Kiota project. The goal of t * [kiota client edit](./cli/client-edit.md) * [kiota client remove](./cli/client-remove.md) * [kiota client generate](./cli/client-generate.md) -* [kiota config init](./cli/config-init.md) -* [kiota config migrate](./cli/config-migrate.md) +* [kiota workspace init](./cli/workspace-init.md) +* [kiota workspace migrate](./cli/workspace-migrate.md) * [kiota download](./cli/download.md) * [kiota info](./cli/info.md) * [kiota login](./cli/login.md) @@ -21,9 +21,9 @@ This repository contains the specifications for the Kiota project. The goal of t ## Scenarios -* [Kiota Config](./scenarios/kiota-config.md) +* [Kiota Config](./scenarios/kiota-workspace.md) * [Telemetry](./scenarios/telemetry.md) ## Schemas -* [kiota-config.json](./schemas/kiota-config.json) +* [workspace.json](./schemas/workspace.json) diff --git a/specs/scenarios/kiota-config.md b/specs/scenarios/kiota-workspace.md similarity index 100% rename from specs/scenarios/kiota-config.md rename to specs/scenarios/kiota-workspace.md diff --git a/specs/scenarios/plugins.md b/specs/scenarios/plugins.md index b268628dcd..e24391c3ff 100644 --- a/specs/scenarios/plugins.md +++ b/specs/scenarios/plugins.md @@ -23,9 +23,9 @@ https://learn.microsoft.com/en-us/semantic-kernel/overview/) as their AI orchest ## Proposal -We should introduce new commands to manage different types of plugins. Also a `plugins` entry should be added to [Kiota config](kiota-config.md). +We should introduce new commands to manage different types of plugins. Also a `plugins` entry should be added to [Kiota workspace](kiota-workspace.md). -Here is an example of what the kiota-config.json file could look like. +Here is an example of what the `workspace.json` file could look like. ```jsonc { diff --git a/specs/schemas/kiota-config.json b/specs/schemas/workspace.json similarity index 100% rename from specs/schemas/kiota-config.json rename to specs/schemas/workspace.json