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 3e17b7fab6..f2962a1a59 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/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 @@ -18,7 +18,6 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file | -- | -- | -- | -- | -- | | `--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 -``` \ No newline at end of file +``` diff --git a/specs/cli/client-edit.md b/specs/cli/client-edit.md index edd6ceb3a6..921e75d78a 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#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,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 { @@ -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 -``` \ 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/config-init.md b/specs/cli/config-init.md deleted file mode 100644 index e924df339e..0000000000 --- a/specs/cli/config-init.md +++ /dev/null @@ -1,34 +0,0 @@ -# `kiota config 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. - -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. - -> [!NOTE] -> If a project only needs a single API, using `kiota config init` is not mandatory as generating code using the `kiota client generate` command could generate a `kiota-config.json` file with values coming from the `kiota client generate` command (if no `kiota-config.json` is present). See [kiota client generate](./client-generate.md) for more information. - -## Parameters - -None. - -## Using `kiota config init` - -```bash -kiota config init -``` - -_The resulting `kiota-config.json` file will look like this:_ - -```jsonc -{ - "version": "1.0.0", -} -``` - -## File structure -```bash -/ - └─kiota-config.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 new file mode 100644 index 0000000000..8c131cc5e4 --- /dev/null +++ b/specs/cli/plugin-add.md @@ -0,0 +1,185 @@ +# kiota plugin add + +## 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 document is generated and kept in the `.kiota/documents/{plugin-name}` 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 document, 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 document file will be stored in the `./.kiota/documents/{plugin-name}` 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 `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 document 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 chosen that will be named `{plugin-name}-{type}.json` and b\) a sliced OpenAPI document 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 `./kiota` 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 `workspace.json` file is generated and the OpenAPI document file is saved locally, the generation will be executed and the plugin and the sliced OpenAPI document 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 the OpenAPI document title. | +| 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 x-ai-description extension from the OpenAPI document. If the x-ai-description is not available, it defaults to `description_for_human` or `Description for {name_for_human}`. | +| contact_email | Defaults to the contact email from the OpenAPI document. If the contact email is not available, it defaults to 'publisher-email@example.com'. | +| logo_url | Defaults to x-logo extension from the OpenAPI document. If the x-logo is not available, the logo_url will not be added in the plugin. | +| legal_info_url | Defaults to x-legal-info-url extension from the OpenAPI document. If the x-legal-info-url is not availabe, the legal_info_url will not be added in the plugin. | +| | | + +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 `{plugin-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 'publisher-email@example.com'. | +| | | + +## Parameters + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--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 document in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | No | +| `--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 | +| `--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 | + +> [!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 `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` + +```bash +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 `workspace.json` file will look like this:_ + +```jsonc +{ + "version": "1.0.0", + "clients": {...}, //if any + "plugins": { + "GitHub": { + "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", "apimanifest"], + "outputDirectory": "./generated/plugins/github", + "overlayDirectory": "./kiota/documents/github/overlay.yaml" + } + } +} +``` + +_The resulting `github-openai.json` file will look like this:_ + +```jsonc +{ + "schema_version": "v1", + "name_for_human": "GitHub v3 REST API", + "name_for_model": "GitHub v3 REST API", + "description_for_human": "GitHub's v3 REST API", + "description_for_model": "Help the user with managing a GitHub repositories. You can view, update and remove repositories.", + "auth": { + "type": "none" + }, + "api": { + "type": "openapi", + "url": "./generated/plugins/github/sliced-openapi-github.json" + }, + "logo_url": "https://example.com/logo.png", + "contact_email": "githubsupport@example.com", + "legal_info_url": "http://www.example.com/view-plugin-information" +} +``` + +_The resulting `github-apimanifest.json` file will look like this:_ + +```jsonc +{ + "apiDependencies": { + "GitHub": { + "x-ms-kiotaHash": "9EDF8506CB74FE44...", + "apiDescriptionUrl": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", + "apiDeploymentBaseUrl": "https://api.github.com/", + "apiDescriptionVersion": "v1.0", + "requests": [ + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}" + }, + { + "method": "PATCH", + "uriTemplate": "/repos/{owner}/{repo}" + }, + { + "method": "DELETE", + "uriTemplate": "/repos/{owner}/{repo}" + } + ] + } + } +} +``` + +_The resulting `apimanifest.json` file (concatenated surface of all APIs dependencies) in the `./kiota` folder will look like this:_ + +```jsonc +{ + "apiDependencies": { + "GraphClient": { //for example, an existing API client for Microsoft Graph + "x-ms-kiotaHash": "9EDF8506CB74FE44...", + "apiDescriptionUrl": "https://aka.ms/graph/v1.0/openapi.yaml", + "apiDeploymentBaseUrl": "https://graph.microsoft.com", + "apiDescriptionVersion": "v1.0", + "requests": [ ...] + }, + "GitHub": { //new plugin added + "x-ms-kiotaHash": "1GFCD345RF3DD98...", + "apiDescriptionUrl": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", + "apiDeploymentBaseUrl": "https://api.github.com/", + "apiDescriptionVersion": "v1.0", + "requests": [ + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}" + }, + { + "method": "PATCH", + "uriTemplate": "/repos/{owner}/{repo}" + }, + { + "method": "DELETE", + "uriTemplate": "/repos/{owner}/{repo}" + } + ] + } + } +} +``` + +## File structure +```bash + └─.kiota + └─workspace.json + └─apimanifest.json # Single artifact with all APIs dependencies info + └─documents + └─github + └─GitHub.json # OpenAPI document + └─overlay.json # Overlay to be applied on top of OpenAPI document + └─generated + └─plugins + └─github + └─github-apimanifest.json # Specific API Manifest + └─github-openai.json #OpenAI Plugin + └─sliced-openapi-github.json # Sliced and augmented OpenAPI document +``` + +[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 new file mode 100644 index 0000000000..588d88e957 --- /dev/null +++ b/specs/cli/plugin-edit.md @@ -0,0 +1,149 @@ +# kiota plugin edit + +## Description + +`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 document location changed or any properties of the plugin entry in `workspace.json`, a new hash composed of the Kiota version, the OpenAPI document 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 `./kiota` 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 `workspace.json` file and the API Manifest are updated, the code generation will be executed based on the newly updated API client configuration. + +## Parameters + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--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 document 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 | +| `--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 | + +> [!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 `workspace.json` file. See the [workspace.json schema](../schemas/workspace.json) for more information. + +## Using `kiota plugin edit` + +```bash +kiota plugin edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}#DELETE" +``` + +_The resulting `workspace.json` file will look like this:_ + +```jsonc +{ + "version": "1.0.0", + "clients": {...}, //if any + "plugins": { + "GitHub": { + "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"], + "outputDirectory": "./generated/plugins/github", + "overlayDirectory": "./overlays/plugins/github/overlay.yaml" + } + } +} +``` + +_The resulting `github-openai.json` file will look like this:_ + +```jsonc +{ + "schema_version": "v1", + "name_for_human": "GitHub Repository Plugin", + "name_for_model": "github", + "description_for_human": "Manage GitHub repositories.", + "description_for_model": "Help the user with managing a GitHub repositories. You can view and update repositories.", + "auth": { + "type": "none" + }, + "api": { + "type": "openapi", + "url": "./sliced-openapi-github.json" + }, + "logo_url": "https://example.com/logo.png", + "contact_email": "githubsupport@example.com", + "legal_info_url": "http://www.example.com/view-plugin-information" +} +``` + +_The resulting `github-apimanifest.json` file will look like this:_ + +```jsonc +{ + "apiDependencies": { + "GitHub": { + "x-ms-kiotaHash": "9EDF8506CB74FE44...", + "apiDescriptionUrl": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", + "apiDeploymentBaseUrl": "https://api.github.com/", + "apiDescriptionVersion": "v1.0", + "requests": [ + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}" + }, + { + "method": "PATCH", + "uriTemplate": "/repos/{owner}/{repo}" + } + ] + } + } +} +``` + +_The resulting `apimanifest.json` file (concatenated surface of all APIs dependencies) in the `./kiota` folder will look like this:_ + +```jsonc +{ + "apiDependencies": { + "GraphClient": { //for example, an existing API client for Microsoft Graph + "x-ms-kiotaHash": "9EDF8506CB74FE44...", + "apiDescriptionUrl": "https://aka.ms/graph/v1.0/openapi.yaml", + "apiDeploymentBaseUrl": "https://graph.microsoft.com", + "apiDescriptionVersion": "v1.0", + "requests": [ ...] + }, + "GitHub": { + "x-ms-kiotaHash": "1GFCD345RF3DD98...", + "apiDescriptionUrl": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", + "apiDeploymentBaseUrl": "https://api.github.com/", + "apiDescriptionVersion": "v1.0", + "requests": [ + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}" + }, + { + "method": "PATCH", + "uriTemplate": "/repos/{owner}/{repo}" + } + ] + } + } +} +``` + +## File structure +```bash + └─.kiota + └─workspace.json + └─apimanifest.json + └─documents + └─github + └─GitHub.json # OpenAPI document + └─overlay.json # Overlay to be applied on top of OpenAPI document + └─generated + └─plugins + └─github + └─github-apimanifest.json # Specific API Manifest + └─github-openai.json #OpenAI Plugin + └─sliced-openapi-github.json # Sliced and augmented OpenAPI document +``` + +[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 new file mode 100644 index 0000000000..1ff13924d1 --- /dev/null +++ b/specs/cli/plugin-generate.md @@ -0,0 +1,30 @@ +# kiota plugin generate + +## Description + +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 `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 `workspace.json` file based on the cached OpenAPI document. If the `--refresh` parameter is provided, the command will refresh the cached OpenAPI document(s), update the different `x-ms-kiotaHash` in the API plugins and then generate the output files for the specified plugins. + +## Parameters + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--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 + +### Using `kiota plugin generate` for a single plugin + +```bash +kiota plugin generate --plugin-name "GitHub" +``` + +### Using `kiota plugin generate` for all plugins + +```bash +kiota plugin generate +``` \ No newline at end of file diff --git a/specs/cli/plugin-remove.md b/specs/cli/plugin-remove.md new file mode 100644 index 0000000000..40e1604a16 --- /dev/null +++ b/specs/cli/plugin-remove.md @@ -0,0 +1,55 @@ +# kiota plugin remove + +## Description + +`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 document 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. + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--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 + +```bash +kiota plugin remove --plugin-name "GitHub" --clean-output +``` +_The resulting `github-apimanifest.json`, `github-openai.json` and `sliced-openapi-github.json` files will be deleted._ + +The resulting `workspace.json` file will look like this: + +```jsonc +{ + "version": "1.0.0", + "clients": {...}, //if any + "plugins": { } +} +``` + +_The resulting `apimanifest.json` file (concatenated surface of all APIs dependencies) in the `./kiota` folder will look like this:_ + +```jsonc +{ + "apiDependencies": { + "GraphClient": { //for example, an existing API client for Microsoft Graph + "x-ms-kiotaHash": "9EDF8506CB74FE44...", + "apiDescriptionUrl": "https://aka.ms/graph/v1.0/openapi.yaml", + "apiDeploymentBaseUrl": "https://graph.microsoft.com", + "apiDescriptionVersion": "v1.0", + "requests": [ ...] + } + } +} //GitHub plugin was removed +``` + +## File structure +```bash +/ + └─.kiota + └─workspace.json + └─apimanifest.json + └─generated + └─plugins +``` \ No newline at end of file diff --git a/specs/cli/workspace-init.md b/specs/cli/workspace-init.md new file mode 100644 index 0000000000..7a196f5026 --- /dev/null +++ b/specs/cli/workspace-init.md @@ -0,0 +1,35 @@ +# `kiota workspace init` + +## Description + +`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 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 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 workspace init` + +```bash +kiota workspace init +``` + +_The resulting `workspace.json` file will look like this:_ + +```jsonc +{ + "version": "1.0.0", +} +``` + +## File structure +```bash +/ + └─.kiota + └─workspace.json +``` \ No newline at end of file diff --git a/specs/cli/config-migrate.md b/specs/cli/workspace-migrate.md similarity index 82% rename from specs/cli/config-migrate.md rename to specs/cli/workspace-migrate.md index ddab8f8d2a..470bdf07a9 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 workspace 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. @@ -13,7 +13,7 @@ In the case where conflicting API client names would be migrated, the command wi | `--lock-directory \| --ld` | No | ./output/pythonClient/ | Relative path to the directory containing the `kiota-lock.json` file. If not specified, all `kiota-lock.json` files within in the current directory tree will be used. | Yes, without its value | | `--client-name \| --cn` | No | graphDelegated | Used with `--lock-directory`, it would allow to specify a name for the API client. Else, name is auto-generated as a concatenation of the `language` and `clientClassName`. | Yes, without its value | -## Using `kiota config migrate` +## Using `kiota workspace migrate` Assuming the following folder structure: ```bash @@ -31,10 +31,10 @@ Assuming the following folder structure: ``` ```bash -kiota config migrate +kiota workspace migrate ``` -_The resulting `kiota-config.json` file will look like this:_ +_The resulting `workspace.json` file will look like this:_ ```jsonc { @@ -112,10 +112,10 @@ _The resulting file structure will look like this:_ └─... # Generated code files └─graph_client.py └─apimanifest.json - └─kiota-config.json + └─workspace.json ``` -## Using `kiota config migrate` for a specific `kiota-lock.json` file and a specific client name +## Using `kiota workspace migrate` for a specific `kiota-lock.json` file and a specific client name Assuming the following folder structure: ```bash @@ -133,10 +133,10 @@ Assuming the following folder structure: ``` ```bash -kiota config migrate --lock-directory ./generated/graph/csharp --client-name GraphClient +kiota workspace migrate --lock-directory ./generated/graph/csharp --client-name GraphClient ``` -_The resulting `kiota-config.json` file will look like this:_ +_The resulting `workspace.json` file will look like this:_ ```jsonc { @@ -166,6 +166,8 @@ _The resulting `kiota-config.json` file will look like this:_ └─.kiota └─definitions └─GraphClient.yaml + └─apimanifest.json + └─workspace.json └─generated └─graph └─csharp @@ -174,7 +176,5 @@ _The resulting `kiota-config.json` file will look like this:_ └─python └─... # Generated code files └─graph_client.py - └─kiota-lock.json - └─apimanifest.json - └─kiota-config.json + └─kiota-lock.json ``` \ No newline at end of file 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 74% rename from specs/scenarios/kiota-config.md rename to specs/scenarios/kiota-workspace.md index b891210bf2..8635611c80 100644 --- a/specs/scenarios/kiota-config.md +++ b/specs/scenarios/kiota-workspace.md @@ -1,4 +1,4 @@ -# Kiota Config +# Kiota Workspace Kiota generates client code for an API and stores parameters in a kiota-lock.json file. A project can contain multiple API clients, but they are independently managed. Kiota has no awareness that an app has a dependency on multiple APIs, even though that is a core use case. @@ -12,11 +12,11 @@ We have previously described Kiota's approach to managing API dependencies as co ## Proposal -We should introduce a new Kiota.config file that holds the input parameters required to generate the API Client code. Currently kiota-lock.json is used to capture what the parameters were at the time of generation and can be used to regenerate based on the parameters in the file. This creates a mixture of purposes for the file. +We should introduce a new Kiota workspace file that holds the input parameters required to generate the API Client code. Currently kiota-lock.json is used to capture what the parameters were at the time of generation and can be used to regenerate based on the parameters in the file. This creates a mixture of purposes for the file. -We did consider creating one kiota-config.json file as as a peer of the language project file, however, for someone who wants to generate multiple clients for an API in different languages, this would be a bit annoying. An alternative would be to allow the kiota-config.json file to move further up the folder structure and support generation in multiple languages from a single file. This is more consistent with what [TypeSpec](https://aka.ms/typespec) are doing and would be helpful for generating CLI and docs as well as a library. +We did consider creating one workspace.json file as a peer of the language project file, however, for someone who wants to generate multiple clients for an API in different languages, this would be a bit annoying. An alternative would be to allow the workspace.json file to move further up the folder structure and support generation in multiple languages from a single file. This is more consistent with what [TypeSpec](https://aka.ms/typespec) are doing and would be helpful for generating CLI and docs as well as a library. -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 { @@ -53,7 +53,7 @@ The [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01. ## Commands -* [kiota config init](../cli/config-init.md) +* [kiota workspace init](../cli/workspace-init.md) * [kiota client add](../cli/client-add.md) * [kiota client edit](../cli/client-edit.md) * [kiota client generate](../cli/client-generate.md) @@ -61,10 +61,10 @@ The [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01. ## End-to-end experience -### Migrate a project that uses Kiota v1.x +### Migrate a project that uses Kiota v1.x for API client ```bash -kiota config migrate +kiota workspace migrate ``` ### Get started to generate an API client @@ -96,4 +96,4 @@ kiota client delete --client=name "graphPython" --clean-output ```bash kiota client generate -``` +``` \ No newline at end of file diff --git a/specs/scenarios/plugins.md b/specs/scenarios/plugins.md new file mode 100644 index 0000000000..af5b4f8844 --- /dev/null +++ b/specs/scenarios/plugins.md @@ -0,0 +1,92 @@ +# Plugins Generation + +Kiota generates client code for an API. With the advancement of the AI, API clients are not the only way one can consume an API. Kiota as a tool that outputs generated files for interacting with an API, should extend its support to also accomplish AI scenarios. + +Today's AI models can easily generate messages and images for users. While this is helpful when building a simple chat app, it is not enough to build fully automated AI agents that can automate business processe and needs specific to one's company and empower users to achieve more. To do so, users need to combine AI models with other sources, such as APIs. + +OpenAI has defined [OpenAI plugins](https://platform.openai.com/docs/plugins/introduction), one way to enable GPT to interact with APIs, allowing it to perform several actions. To build a plugin, it's necessary to create a [plugin manifest file](https://platform.openai.com/docs/plugins/getting-started/plugin-manifest) that defines relevant metadata information that allows GPT to call an API. + +In addition to OpenAI plugin manifest, [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html) is another way to declare dependencies of APIs and their characteristics. API Manifest addresses a limitation present in both the OpenAI plugin manifest and OpenAPI document, it can references one or more OpenAPI documents as dependencies. +For developers using [Semantic Kernel]( +https://learn.microsoft.com/en-us/semantic-kernel/overview/) as their AI orchestractor, [API Manifest is supported as a input format](https://github.com/microsoft/semantic-kernel/pull/4961), in preview state, for plugin generation. + + +## Current Challenges + +- Creating custom GPTs and AI plugins for existing APIs, specially for big APIs, requires great amount of effort. +- Kiota is currently specialized in client code generation and it doesn't meet the market expansion for AI. + +## Goals + +- Enable developers to customize Copilot to be more helpful in their daily lives, at specific tasks, at work, at home by providing tools to output OpenAI plugin manifests. +- Enable developers to generate API Manifest that can be converted into Semantic Kernel API Manifest Plugins. + +## Proposal + +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 `workspace.json` file could look like. + +```jsonc +{ + "version": "1.0.0", + "clients": { ... }, //if any + "plugins": { + "GitHub": { + "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"], + "outputDirectory": "./generated/plugins/github", + "overlayDirectory": "./kiota/documents/github/overlay.yaml" + } + } +} +``` + +## Commands + +In addition to managing clients: +* [kiota client add](../cli/client-add.md) +* [kiota client edit](../cli/client-edit.md) +* [kiota client generate](../cli/client-generate.md) +* [kiota client remove](../cli/client-remove.md) + +We will provide plugins commands: +* [kiota plugin add](../cli/plugin-add.md) +* [kiota plugin edit](../cli/plugin-edit.md) +* [kiota plugin generate](../cli/plugin-generate.md) +* [kiota plugin remove](../cli/plugin-remove.md) + + +## End-to-end experience + +### Add a plugin + +```bash +kiota plugin add --plugin-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 --output "./generated/plugins/github" +``` + +### Edit a plugin + +```bash +kiota plugin edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}#DELETE" +``` + +### Remove a plugin + +```bash +kiota plugin remove --plugin-name "GitHub" --clean-output +``` + +### Generate all plugins + +```bash +kiota plugin generate +``` + +### Generate a specific plugins + +```bash +kiota plugin generate --plugin-name "GitHub" +``` \ No newline at end of file diff --git a/specs/scenarios/telemetry.md b/specs/scenarios/telemetry.md index fad4f250b0..b17ea233a7 100644 --- a/specs/scenarios/telemetry.md +++ b/specs/scenarios/telemetry.md @@ -1,6 +1,6 @@ # Telemetry -Kiota is a tool that generates code for interacting with an API. It is used by developers to create applications that interact with an API. It is also used by API owners to create SDKs for their API. In both cases, it is important to understand how the tool is being used and what are the scenarios leveraged by our community. This document describes the telemetry we plan to collect and how we use it. +Kiota is a tool that generates code for interacting with an API. It is used by developers and API owners to create code clients that interact with APIs. And with the new commands that generate plugins, it will also be used for developers to create AI plugins. In both cases, it is important to understand how the tool is being used and what are the scenarios leveraged by our community. This document describes the telemetry we plan to collect and how we use it. ## Current Challenges @@ -48,6 +48,8 @@ We should be very careful about the information we collect. Before rolling out t - What are the most used commands? - How are the commands used? Which parameters are being used? - What are the most used languages? +- Are users levaring Kiota for AI? +- What are the most used type of plugin? - What are the most used platforms? - Is there a difference in how the CLI is being used between platforms? - Do we have users using old versions of kiota? Why? diff --git a/specs/schemas/kiota-config.json b/specs/schemas/workspace.json similarity index 62% rename from specs/schemas/kiota-config.json rename to specs/schemas/workspace.json index a4797a7f3e..f0c683d415 100644 --- a/specs/schemas/kiota-config.json +++ b/specs/schemas/workspace.json @@ -62,6 +62,46 @@ "type": "string" } } + }, + "plugins": { + "type": "object", + "patternProperties": { + ".*": { + "type": "object", + "properties": { + "descriptionLocation": { + "type": "string" + }, + "includePatterns": { + "type": "array", + "items": { + "type": "string" + } + }, + "excludePatterns": { + "type": "array", + "items": { + "type": "string" + } + }, + "type": { + "type": "string" + }, + "outputPath": { + "type": "string" + }, + "overlayDirectory": { + "type": "string" + } + } + } + }, + "disabledValidationRules": { + "type": "array", + "items": { + "type": "string" + } + } } } -} +} \ No newline at end of file