Merge pull request #4124 from microsoft/specs/kiota-plugin

Specs/kiota plugin

.vscode/settings.json

@@ -22,6 +22,7 @@
   ],
   "cSpell.words": [
     "allof",
+    "apimanifest",
     "apisguru",
     "autoload",
     "Contoso",

specs/cli/client-add.md

@@ -2,23 +2,22 @@
 
 ## 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/documents/{client-name}` 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. 
+Every time an API client is added, a copy of the OpenAPI description file will be stored in the `./.kiota/documents/{client-name}/{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#section-2.5-3) file will be generated (if non existing) or edited (if already existing) to represent the surface of the API being used. This file will be named `apimanifest.json` and next to the `kiota-config.json`. This file 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#section-2.5-3).
+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 `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
 
 | Parameters | Required | Example | Description | Telemetry |
 | -- | -- | -- | -- | -- |
 | `--client-name \| --cn` | Yes | graphDelegated | Name of the client and the client class. Unique within the parent API. Defaults to `Client` | No |
 | `--openapi \| -d` | Yes | https://aka.ms/graph/v1.0/openapi.yaml | The location of the OpenAPI description in JSON or YAML format to use to generate the SDK. Accepts a URL or a local path. | No |
-| `--search-key \| --sk` | No | github::microsoftgraph/msgraph-metadata/graph.microsoft.com/v1.0 | The search key used to locate the OpenAPI description. | Yes, without its value |
 | `--include-path \| -i` | No | /me/chats#GET | 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 | \*\*/users/\*\* | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value |
 | `--language \| -l` | Yes | csharp | The target language for the generated code files or for the information. | Yes |
@@ -27,10 +26,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 +39,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 +104,18 @@ _The resulting `apimanifest.json` file will look like this:_
 ```
 
 ## File structure
+
 ```bash
 /
  └─.kiota
-    └─clients
-       └─GraphClient.yaml
+    └─apimanifest.json
+    └─workspace.json 
+    └─documents
+       └─GraphClient
+         └─GraphClient.yaml
  └─generated
     └─graph
        └─csharp
           └─... # Generated code files
           └─GraphClient.cs       
- └─apimanifest.json
- └─kiota-config.json 
-```
+```

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#section-2.5-3).
+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,15 +25,15 @@ 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`
 
 ```bash
 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
 {
@@ -101,13 +101,14 @@ _The resulting `apimanifest.json` file will look like this:_
 ```bash
 /
  └─.kiota
-    └─clients
-       └─GraphClient.yaml
+    └─apimanifest.json
+    └─workspace.json 
+    └─documents
+       └─GraphClient
+         └─GraphClient.yaml
  └─generated
     └─graph
        └─csharp
           └─... # Generated code files
           └─GraphClient.cs  
- └─apimanifest.json
- └─kiota-config.json 
-```
+```

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
 

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
-```
+```

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)