From 6a075876fa34a6575c32132f6dccbcc6c16ad4c1 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Fri, 2 Feb 2024 15:23:50 -0300 Subject: [PATCH 01/22] plugin-add --- specs/cli/plugin-add.md | 102 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 specs/cli/plugin-add.md diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md new file mode 100644 index 0000000000..69a2a8d66c --- /dev/null +++ b/specs/cli/plugin-add.md @@ -0,0 +1,102 @@ +# kiota plugin add + +## Description + +`kiota plugin add` allows a developer to add a new manifest 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. + +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-plugins` will be generated (if non existing) or updated (if already existing) in the root folder next to `kiota-config.json`. This file will represent a concatenated surface of all APIs used across plugins. A new hash composed of the Kiota version, the OpenAPI description location and the properties of the plugins will be generated and would trigger an update to the [API Manifest][def]. + +Developers can generate `typea`, `typeb` and `apimanifest`. By generating `typea` or `typeb`, two outputs will be generated: a\) the manifest type you have choosen that will be named `{plugin-name}-{type}.json` and b\) an [API Manifest][def] which will be named `{plugin-name}-apimanifest.json` that will include only the information for this specific plugin. `apimanifest` will generate only an API Manifest. +> [!NOTE] +> There will be two different [API Manifests][def]. One in the root folder representing a concatenated surface of all APIs and a second one specific to each plugin saved in the choosen output directory. + +Once the `kiota-config.json` file is generated and the OpenAPI description file is saved locally, the generation will be executed and the manifest will become available. + +## Parameters + +| Parameters | Required | Example | Description | +| -- | -- | -- | -- | +| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | +| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | +| `--include-path \| -i` | No | /issues/\*\* | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | +| `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | +| `--type \| -t` | Yes | typea | The target type of manifest for the generated output files. Possible values are `typea`, `typeb` and `apimanifest`. Defaults to `apimanifest`| +| `--overlayDirectory \| --od` | No | ./overlay/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. | +| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | +| `--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`. | + +> [!NOTE] +> It is not required to use the CLI to add new plugins. It is possible to add a new plugins by adding a new entry in the `plugins` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-plugin-config.json) for more information. Using `kiota plugin generate --plugin-name myPlugin` would be required to generate the manifests. + +## Using `kiota plugin add` + +```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 "/issues/**" --type typea --output "./generated/plugins/github" +``` + +_The resulting `kiota-config.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", + "type": "typea", + "includePatterns": ["/issues/**"], + "excludePatterns": [], + "outputDirectory": "./generated/plugins/github", + "overlayDirectory": "./overlays/plugins/github/overlay.yaml" + } + } +} +``` + +_The resulting `github-typea.json` file will look like this:_ + +```jsonc + +``` + +_The resulting `github-apimanifest.json` file will look like this:_ + +```jsonc +{ + "apiDependencies": { + "GraphClient": { + "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": "/issues" + } + ] + } + } +} +``` + +## File structure +```bash +/ + └─.kiota + └─plugins + └─GitHub.json + └─generated + └─plugins + └─github + └─github-typea.json + └─github-apimanifest.json + └─kiota-config.json + └─apimanifest.json +``` + +[def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html#section-2.5-3 \ No newline at end of file From a67f30fddeb68de23f1402d694a8c5f6c03715a6 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Sat, 3 Feb 2024 11:08:38 -0300 Subject: [PATCH 02/22] Edited kiota-config and added plugin-edit --- specs/cli/plugin-add.md | 34 ++++++++-- specs/cli/plugin-edit.md | 109 ++++++++++++++++++++++++++++++++ specs/schemas/kiota-config.json | 42 +++++++++++- 3 files changed, 179 insertions(+), 6 deletions(-) create mode 100644 specs/cli/plugin-edit.md diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index 69a2a8d66c..0729758970 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -22,7 +22,7 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file | -- | -- | -- | -- | | `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | -| `--include-path \| -i` | No | /issues/\*\* | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | +| `--include-path \| -i` | No | /repos/\*\* | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | | `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | | `--type \| -t` | Yes | typea | The target type of manifest for the generated output files. Possible values are `typea`, `typeb` and `apimanifest`. Defaults to `apimanifest`| | `--overlayDirectory \| --od` | No | ./overlay/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. | @@ -35,7 +35,7 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file ## Using `kiota plugin add` ```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 "/issues/**" --type typea --output "./generated/plugins/github" +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/**" --type typea --output "./generated/plugins/github" ``` _The resulting `kiota-config.json` file will look like this:_ @@ -47,9 +47,9 @@ _The resulting `kiota-config.json` file will look like this:_ "plugins": { "GitHub": { "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", - "type": "typea", - "includePatterns": ["/issues/**"], + "includePatterns": ["/repos/**"], "excludePatterns": [], + "type": "typea", "outputDirectory": "./generated/plugins/github", "overlayDirectory": "./overlays/plugins/github/overlay.yaml" } @@ -76,7 +76,31 @@ _The resulting `github-apimanifest.json` file will look like this:_ "requests": [ { "method": "GET", - "uriTemplate": "/issues" + "uriTemplate": "/repos/{owner}/{repo}" + }, + { + "method": "PATCH", + "uriTemplate": "/repos/{owner}/{repo}" + },, + { + "method": "DELETE", + "uriTemplate": "/repos/{owner}/{repo}" + }, + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts" + }, + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" + }, + { + "method": "DELETE", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" + }, + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}/actions/cache/usage" } ] } diff --git a/specs/cli/plugin-edit.md b/specs/cli/plugin-edit.md new file mode 100644 index 0000000000..dc2c62bbab --- /dev/null +++ b/specs/cli/plugin-edit.md @@ -0,0 +1,109 @@ +# kiota plugin edit + +## Description + +`kiota plugin update` allows a developer to edit an existing manifest int 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. + +When executing, the API 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 plugin will be generated and and would trigger an update to the [API Manifest][def] located in the root folder. +> [!NOTE] +> There will be two different [API Manifests][def]. One in the root folder representing a concatenated surface of all APIs and a second one specific to each plugin saved in the choosen output directory. + +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. + +## Parameters + +| Parameters | Required | Example | Description | +| -- | -- | -- | -- | +| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | +| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | +| `--include-path \| -i` | No | /repos/\*\* | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | +| `--exclude-path \| -e` | No | /repos/{owner}/{repo}/actions/cache/usage | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | +| `--type \| -t` | Yes | typea | The target type of manifest for the generated output files. Possible values are `typea`, `typeb` and `apimanifest`. Defaults to `apimanifest`| +| `--overlayDirectory \| --od` | No | ./overlay/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. | +| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | +| `--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`. | + +> [!NOTE] +> It is not required to use the CLI to edit plugins. It is possible to edit a plugins by modifying its entry in the `plugins` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-plugin-config.json) for more information. + +## Using `kiota plugin edit` + +```bash +kiota plugin edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}/actions/cache/usage" +``` + +_The resulting `kiota-config.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/**"], + "excludePatterns": ["/repos/{owner}/{repo}/actions/cache/usage"], + "type": "typea", + "outputDirectory": "./generated/plugins/github", + "overlayDirectory": "./overlays/plugins/github/overlay.yaml" + } + } +} +``` + +_The resulting `github-apimanifest.json` file will look like this:_ + +```jsonc +{ + "apiDependencies": { + "GraphClient": { + "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}" + }, + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts" + }, + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" + }, + { + "method": "DELETE", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" + } + ] + } + } +} +``` + +## File structure +```bash + └─.kiota + └─plugins + └─GitHub.json + └─generated + └─plugins + └─github + └─github-typea.json + └─github-apimanifest.json + └─kiota-config.json + └─apimanifest.json +``` + +[def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html#section-2.5-3 \ No newline at end of file diff --git a/specs/schemas/kiota-config.json b/specs/schemas/kiota-config.json index a4797a7f3e..f0c683d415 100644 --- a/specs/schemas/kiota-config.json +++ b/specs/schemas/kiota-config.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 From cc189cae1e41bc440b7ca95b86d4c1275ed3ef99 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Sat, 3 Feb 2024 11:19:11 -0300 Subject: [PATCH 03/22] Added plugin-generate --- specs/cli/plugin-generate.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 specs/cli/plugin-generate.md diff --git a/specs/cli/plugin-generate.md b/specs/cli/plugin-generate.md new file mode 100644 index 0000000000..ccf1b15761 --- /dev/null +++ b/specs/cli/plugin-generate.md @@ -0,0 +1,30 @@ +# kiota plugin generate + +## Description + +Now that we have a `kiota-config.json` file, all the parameters required to generate the plugin 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. + +It's also possible to specify for which plugin the output files should be generated. This is useful when there are multiple plugins. The `kiota plugin generate --plugin-name "MyPlugin"` command will read the `kiota-config.json` file and generate the code 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 outfiles 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 Manifests and then generate the output files for the specified plugins. + +## Parameters + +| Parameters | Required | Example | Description | +| -- | -- | -- | -- | +| `--plugin-name \| --cn` | No | GitHub | Name of the plugin. Unique within the parent API. | +| `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. | + +## 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 From 1d30b3bc6e641a3842a632b319baf70231bd7354 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Sat, 3 Feb 2024 11:39:32 -0300 Subject: [PATCH 04/22] Added plugin-removed --- specs/cli/plugin-add.md | 59 +++++++++++++++++++++++++++++++-- specs/cli/plugin-edit.md | 54 +++++++++++++++++++++++++++++- specs/cli/plugin-remove.md | 67 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 177 insertions(+), 3 deletions(-) create mode 100644 specs/cli/plugin-remove.md diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index 0729758970..4fd99245de 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -68,7 +68,59 @@ _The resulting `github-apimanifest.json` file will look like this:_ ```jsonc { "apiDependencies": { - "GraphClient": { + "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}" + }, + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts" + }, + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" + }, + { + "method": "DELETE", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" + }, + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}/actions/cache/usage" + } + ] + } + } +} +``` + +_The resulting `apimanifest.json` file (concatenated surface of all APIs) will look like this:_ + +```jsonc +{ + "apiDependencies": { + "GraphPlugin": { + "x-ms-kiotaHash": "1GFCD345RF3DD98...", + "apiDescriptionUrl": "https://aka.ms/graph/v1.0/openapi.yaml", + "apiDeploymentBaseUrl": "https://graph.microsoft.com", + "apiDescriptionVersion": "v1.0", + "requests": [ ... ] + }, + "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/", @@ -110,12 +162,15 @@ _The resulting `github-apimanifest.json` file will look like this:_ ## File structure ```bash -/ └─.kiota └─plugins + └─GraphPlugin.yaml └─GitHub.json └─generated └─plugins + └─graphplugin + └─graphplugin-typeb.json + └─graphplugin-apimanifest.json └─github └─github-typea.json └─github-apimanifest.json diff --git a/specs/cli/plugin-edit.md b/specs/cli/plugin-edit.md index dc2c62bbab..f0521199be 100644 --- a/specs/cli/plugin-edit.md +++ b/specs/cli/plugin-edit.md @@ -56,7 +56,55 @@ _The resulting `github-apimanifest.json` file will look like this:_ ```jsonc { "apiDependencies": { - "GraphClient": { + "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}" + }, + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts" + }, + { + "method": "GET", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" + }, + { + "method": "DELETE", + "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" + } + ] + } + } +} +``` + +_The resulting `apimanifest.json` file (concatenated surface of all APIs) will look like this:_ + +```jsonc +{ + "apiDependencies": { + "GraphPlugin": { + "x-ms-kiotaHash": "1GFCD345RF3DD98...", + "apiDescriptionUrl": "https://aka.ms/graph/v1.0/openapi.yaml", + "apiDeploymentBaseUrl": "https://graph.microsoft.com", + "apiDescriptionVersion": "v1.0", + "requests": [ ... ] + }, + "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/", @@ -96,9 +144,13 @@ _The resulting `github-apimanifest.json` file will look like this:_ ```bash └─.kiota └─plugins + └─GraphPlugin.yaml └─GitHub.json └─generated └─plugins + └─graphplugin + └─graphplugin-typeb.json + └─graphplugin-apimanifest.json └─github └─github-typea.json └─github-apimanifest.json diff --git a/specs/cli/plugin-remove.md b/specs/cli/plugin-remove.md new file mode 100644 index 0000000000..028cd4dd47 --- /dev/null +++ b/specs/cli/plugin-remove.md @@ -0,0 +1,67 @@ +# kiota plugin remove + +## 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. + +The command also has one optional parameter, the ability to remove the generated plugin. 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 Manifests). The API Manifests are also updated to remove the dependency from the list of dependencies. + +| Parameters | Required | Example | Description | +| -- | -- | -- | -- | +| `--plugin-name \| --cn` | Yes | GitHub | Name of the plugin | +| `--clean-output \| --co` | No | | Cleans the generated plugin | + +#### Using kiota plugin remove + +```bash +kiota plugin remove --plugin-name "GitHub" --clean-output +``` + +The resulting `kiota-config.json` file will look like this: + +```jsonc +{ + "version": "1.0.0", + "plugins": { } +} +``` + +_The resulting `github-apimanifest.json` file will look like this:_ + +```jsonc +{ + "apiDependencies": { } +} +``` + +_The resulting `apimanifest.json` file (concatenated surface of all APIs) will look like this:_ + +```jsonc +{ + "apiDependencies": { + "GraphPlugin": { + "x-ms-kiotaHash": "1GFCD345RF3DD98...", + "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 + └─plugins + └─GraphPlugin.yaml + └─generated + └─plugins + └─graphplugin + └─graphplugin-typeb.json + └─graphplugin-apimanifest.json + └─github + └─kiota-config.json + └─apimanifest.json +``` \ No newline at end of file From 736a3b36ad967a6573ddff91b4e82f9504bc25bb Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Sat, 3 Feb 2024 11:41:51 -0300 Subject: [PATCH 05/22] Updated config-init --- specs/cli/config-init.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/cli/config-init.md b/specs/cli/config-init.md index e924df339e..29efcf548a 100644 --- a/specs/cli/config-init.md +++ b/specs/cli/config-init.md @@ -7,7 +7,7 @@ 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. +> If a project only needs a single API, using `kiota config init` is not mandatory as generating code using the `kiota client generate` or `kiota plugin generate` command could generate a `kiota-config.json` file with values coming from the `kiota client generate` or `kiota plugin generate` commands (if no `kiota-config.json` is present). See [kiota client generate](./client-generate.md) or [kiota plugin generate](./plugin-generate.md) for more information. ## Parameters From b69a9a3b5f34f1979ec416f372fa2cf7c8714146 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Tue, 27 Feb 2024 15:59:08 -0300 Subject: [PATCH 06/22] Updating from "plugin" to "manifest" --- specs/cli/{plugin-add.md => manifest-add.md} | 22 +++---- .../cli/{plugin-edit.md => manifest-edit.md} | 27 +++++---- specs/cli/manifest-generate.md | 30 ++++++++++ .../{plugin-remove.md => manifest-remove.md} | 22 +++---- specs/cli/plugin-generate.md | 30 ---------- specs/scenarios/kiota-config.md | 59 ++++++++++++++++--- 6 files changed, 115 insertions(+), 75 deletions(-) rename specs/cli/{plugin-add.md => manifest-add.md} (67%) rename specs/cli/{plugin-edit.md => manifest-edit.md} (72%) create mode 100644 specs/cli/manifest-generate.md rename specs/cli/{plugin-remove.md => manifest-remove.md} (53%) delete mode 100644 specs/cli/plugin-generate.md diff --git a/specs/cli/plugin-add.md b/specs/cli/manifest-add.md similarity index 67% rename from specs/cli/plugin-add.md rename to specs/cli/manifest-add.md index 4fd99245de..14ae7bf379 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/manifest-add.md @@ -1,16 +1,16 @@ -# kiota plugin add +# kiota manifest add ## Description -`kiota plugin add` allows a developer to add a new manifest 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 manifest add` allows a developer to add a new plugin manifest 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 manifest with the same name already exists, the command will fail and display an actionnable 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. +When executing, a new plugin manifest 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. +Every time a plugin manifest 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-plugins` will be generated (if non existing) or updated (if already existing) in the root folder next to `kiota-config.json`. This file will represent a concatenated surface of all APIs used across plugins. A new hash composed of the Kiota version, the OpenAPI description location and the properties of the plugins will be generated and would trigger an update to the [API Manifest][def]. -Developers can generate `typea`, `typeb` and `apimanifest`. By generating `typea` or `typeb`, two outputs will be generated: a\) the manifest type you have choosen that will be named `{plugin-name}-{type}.json` and b\) an [API Manifest][def] which will be named `{plugin-name}-apimanifest.json` that will include only the information for this specific plugin. `apimanifest` will generate only an API Manifest. +Developers can generate `typea` and `apimanifest` plugin manifests. By generating `typea`, two outputs will be generated: a\) the manifest type you have choosen that will be named `{plugin-name}-{type}.json` and b\) an [API Manifest][def] which will be named `{plugin-name}-apimanifest.json` that will include only the information for this specific plugin. `apimanifest` will generate only an API Manifest. > [!NOTE] > There will be two different [API Manifests][def]. One in the root folder representing a concatenated surface of all APIs and a second one specific to each plugin saved in the choosen output directory. @@ -20,22 +20,22 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file | Parameters | Required | Example | Description | | -- | -- | -- | -- | -| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | +| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `PluginManifest` | | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | | `--include-path \| -i` | No | /repos/\*\* | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | | `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | -| `--type \| -t` | Yes | typea | The target type of manifest for the generated output files. Possible values are `typea`, `typeb` and `apimanifest`. Defaults to `apimanifest`| -| `--overlayDirectory \| --od` | No | ./overlay/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. | +| `--type \| -t` | Yes | typea | The target type of manifest for the generated output files. Possible values are `typea` and `apimanifest`. Defaults to `apimanifest`| +| `--overlayDirectory \| --od` | No | ./overlay/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin manifest. [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. | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | | `--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`. | > [!NOTE] -> It is not required to use the CLI to add new plugins. It is possible to add a new plugins by adding a new entry in the `plugins` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-plugin-config.json) for more information. Using `kiota plugin generate --plugin-name myPlugin` would be required to generate the manifests. +> It is not required to use the CLI to add new manifests. It is possible to add a new plugin manifest by adding a new entry in the `plugins` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-plugin-config.json) for more information. Using `kiota manifest generate --plugin-name myPluginManifest` would be required to generate the manifests. -## Using `kiota plugin add` +## Using `kiota manifest add` ```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/**" --type typea --output "./generated/plugins/github" +kiota manifest 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/**" --type typea --output "./generated/plugins/github" ``` _The resulting `kiota-config.json` file will look like this:_ diff --git a/specs/cli/plugin-edit.md b/specs/cli/manifest-edit.md similarity index 72% rename from specs/cli/plugin-edit.md rename to specs/cli/manifest-edit.md index f0521199be..529ac3ccb7 100644 --- a/specs/cli/plugin-edit.md +++ b/specs/cli/manifest-edit.md @@ -1,12 +1,12 @@ -# kiota plugin edit +# kiota manifest edit ## Description -`kiota plugin update` allows a developer to edit an existing manifest int 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 manifest update` allows a developer to edit an existing plugin manifest 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. -When executing, the API 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 plugin will be generated and and would trigger an update to the [API Manifest][def] located in the root folder. +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 manifest. 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 plugin manifest will be generated and and would trigger an update to the [API Manifest][def] located in the root folder. > [!NOTE] -> There will be two different [API Manifests][def]. One in the root folder representing a concatenated surface of all APIs and a second one specific to each plugin saved in the choosen output directory. +> There will be two different [API Manifests][def]. One in the root folder representing a concatenated surface of all APIs and a second one specific to each plugin manifest saved in the choosen output directory. 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. @@ -14,22 +14,22 @@ Once the `kiota-config.json` file and the API Manifest are updated, the code gen | Parameters | Required | Example | Description | | -- | -- | -- | -- | -| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | +| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `PluginManifest` | | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | | `--include-path \| -i` | No | /repos/\*\* | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | | `--exclude-path \| -e` | No | /repos/{owner}/{repo}/actions/cache/usage | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | -| `--type \| -t` | Yes | typea | The target type of manifest for the generated output files. Possible values are `typea`, `typeb` and `apimanifest`. Defaults to `apimanifest`| -| `--overlayDirectory \| --od` | No | ./overlay/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. | +| `--type \| -t` | Yes | typea | The target type of manifest for the generated output files. Possible values are `typea` and `apimanifest`. Defaults to `apimanifest`| +| `--overlayDirectory \| --od` | No | ./overlay/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin manifest. [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. | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | | `--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`. | > [!NOTE] -> It is not required to use the CLI to edit plugins. It is possible to edit a plugins by modifying its entry in the `plugins` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-plugin-config.json) for more information. +> It is not required to use the CLI to edit plugin manifests. It is possible to edit a plugins by modifying its entry in the `plugins` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-plugin-config.json) for more information. -## Using `kiota plugin edit` +## Using `kiota manifest edit` ```bash -kiota plugin edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}/actions/cache/usage" +kiota manifest edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}/actions/cache/usage" ``` _The resulting `kiota-config.json` file will look like this:_ @@ -51,6 +51,12 @@ _The resulting `kiota-config.json` file will look like this:_ } ``` +_The resulting `github-typea.json` file will look like this:_ + +```jsonc + +``` + _The resulting `github-apimanifest.json` file will look like this:_ ```jsonc @@ -149,7 +155,6 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l └─generated └─plugins └─graphplugin - └─graphplugin-typeb.json └─graphplugin-apimanifest.json └─github └─github-typea.json diff --git a/specs/cli/manifest-generate.md b/specs/cli/manifest-generate.md new file mode 100644 index 0000000000..6f67fdf27b --- /dev/null +++ b/specs/cli/manifest-generate.md @@ -0,0 +1,30 @@ +# kiota manifest generate + +## Description + +Now that we have a `kiota-config.json` file, all the parameters required to generate the plugin manifests are stored in the file. The `kiota manifest generate` command will read the `kiota-config.json` file and generate the output files for each of the available plugins. + +It's also possible to specify for which plugin manifest the output files should be generated. This is useful when there are multiple plugin manifests. The `kiota manifest generate --plugin-name "MyPluginManifest"` command will read the `kiota-config.json` file and generate the code for the specified plugin manifest. If it can't find the specified plugin manifest, it will throw an error. + +In general cases, the `kiota manifest generate` command will generate the outfiles for all the plugin manifests 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 Manifests and then generate the output files for the specified plugins. + +## Parameters + +| Parameters | Required | Example | Description | +| -- | -- | -- | -- | +| `--plugin-name \| --cn` | No | GitHub | Name of the plugin. Unique within the parent API. | +| `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. | + +## Usage + +### Using `kiota manifest generate` for a single plugin manifest + +```bash +kiota manifest generate --plugin-name "GitHub" +``` + +### Using `kiota manifest generate` for all plugin manifests + +```bash +kiota manifest generate +``` \ No newline at end of file diff --git a/specs/cli/plugin-remove.md b/specs/cli/manifest-remove.md similarity index 53% rename from specs/cli/plugin-remove.md rename to specs/cli/manifest-remove.md index 028cd4dd47..9f5d405a53 100644 --- a/specs/cli/plugin-remove.md +++ b/specs/cli/manifest-remove.md @@ -1,21 +1,22 @@ -# kiota plugin remove +# kiota manifest remove ## 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 manifest remove` allows a developer to remove an existing plugin manifest 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 manifest. -The command also has one optional parameter, the ability to remove the generated plugin. 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 Manifests). The API Manifests are also updated to remove the dependency from the list of dependencies. +The command also has one optional parameter, the ability to remove the generated plugin manifest. 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 Manifests). The API Manifests are also updated to remove the dependency from the list of dependencies. | Parameters | Required | Example | Description | | -- | -- | -- | -- | | `--plugin-name \| --cn` | Yes | GitHub | Name of the plugin | | `--clean-output \| --co` | No | | Cleans the generated plugin | -#### Using kiota plugin remove +#### Using kiota manifest remove and deleting all the content ```bash -kiota plugin remove --plugin-name "GitHub" --clean-output +kiota manifest remove --plugin-name "GitHub" --clean-output ``` +_The resulting `github-apimanifest.json` and `github-typea.json` files will be deleted._ The resulting `kiota-config.json` file will look like this: @@ -26,14 +27,6 @@ The resulting `kiota-config.json` file will look like this: } ``` -_The resulting `github-apimanifest.json` file will look like this:_ - -```jsonc -{ - "apiDependencies": { } -} -``` - _The resulting `apimanifest.json` file (concatenated surface of all APIs) will look like this:_ ```jsonc @@ -47,7 +40,7 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l "requests": [ ... ] } } -} //GitHub plugin was removed +} //GitHub plugin manifest was removed ``` ## File structure @@ -59,7 +52,6 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l └─generated └─plugins └─graphplugin - └─graphplugin-typeb.json └─graphplugin-apimanifest.json └─github └─kiota-config.json diff --git a/specs/cli/plugin-generate.md b/specs/cli/plugin-generate.md deleted file mode 100644 index ccf1b15761..0000000000 --- a/specs/cli/plugin-generate.md +++ /dev/null @@ -1,30 +0,0 @@ -# kiota plugin generate - -## Description - -Now that we have a `kiota-config.json` file, all the parameters required to generate the plugin 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. - -It's also possible to specify for which plugin the output files should be generated. This is useful when there are multiple plugins. The `kiota plugin generate --plugin-name "MyPlugin"` command will read the `kiota-config.json` file and generate the code 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 outfiles 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 Manifests and then generate the output files for the specified plugins. - -## Parameters - -| Parameters | Required | Example | Description | -| -- | -- | -- | -- | -| `--plugin-name \| --cn` | No | GitHub | Name of the plugin. Unique within the parent API. | -| `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. | - -## 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/scenarios/kiota-config.md b/specs/scenarios/kiota-config.md index b891210bf2..d0990d5d9c 100644 --- a/specs/scenarios/kiota-config.md +++ b/specs/scenarios/kiota-config.md @@ -7,14 +7,15 @@ Kiota generates client code for an API and stores parameters in a kiota-lock.jso - Client code generation is not reproducible if API description changes - Kiota doesn't have an obvious solution for APIs that use multiple security schemes. - Kiota doesn't have an obvious solution for projects utilizing multiple APIs. +- Kiota is currently specialized in client code generation and [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html#section-2.5-3) and it doesn't meet the market expansion for AI scenarios. We have previously described Kiota's approach to managing API dependencies as consistent with the way people manage packages in a project. However, currently our tooling doesn't behave that way. We treat each dependency independently. ## 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.config file that holds the input parameters required to generate either the API Client code or AI plugin manifests. 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 kiota-config.json file as a peer of the language project file, however, for someone who wants to generate multiple clients in different languages and plugin manifests for an API, 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. Here is an example of what the kiota-config.json file could look like. @@ -42,6 +43,16 @@ Here is an example of what the kiota-config.json file could look like. "excludePatterns": [], "language": "csharp", "outputPath": "./generated/businessCentral" + }, + "plugins": { + "GitHub": { + "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", + "includePatterns": ["/repos/**"], + "excludePatterns": [], + "type": "typea", + "outputDirectory": "./generated/plugins/github", + "overlayDirectory": "./overlays/plugins/github/overlay.yaml" + } } } } @@ -58,42 +69,74 @@ The [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01. * [kiota client edit](../cli/client-edit.md) * [kiota client generate](../cli/client-generate.md) * [kiota client remove](../cli/client-remove.md) +* [kiota manifest add](../cli/manifest-add.md) +* [kiota manifest edit](../cli/manifest-edit.md) +* [kiota manifest generate](../cli/manifest-generate.md) +* [kiota manifest remove](../cli/manifest-remove.md) ## End-to-end experience -### Migrate a project that uses Kiota v1.x +### APIs clients + +- #### Migrate a project that uses Kiota v1.x for API client ```bash kiota config migrate ``` -### Get started to generate an API client +- #### Get started to generate an API client ```bash kiota client init kiota client add --client-name "GraphClient" --openapi "https://aka.ms/graph/v1.0/openapi.yaml" --language csharp --output "./csharpClient" ``` -### Add a second API client +- #### Add a second API client ```bash kiota client add --clientName "graphPython" --openapi "https://aka.ms/graph/v1.0/openapi.yaml" --language python --outputPath ./pythonClient ``` -### Edit an API client +- #### Edit an API client ```bash kiota client edit --client-name "GraphClient" --exclude-path "/users/$count" ``` -### Remove a language and delete the generated code +- #### Remove a language and delete the generated code ```bash kiota client delete --client=name "graphPython" --clean-output ``` -### Generate code for all API clients +- #### Generate code for all API clients ```bash kiota client generate ``` + +### AI Plugin Manifests + +- #### Add a plugin manifest + +```bash +kiota manifest 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/**" --type typea --output "./generated/plugins/github" +``` + +- #### Edit an AI plugin manifest + +```bash +kiota manifest edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}/actions/cache/usage" +``` + +- #### Remove an AI plugin manifest + +```bash +kiota manifest remove --plugin-name "GitHub" --clean-output +``` + +- #### Generate all AI plugin manifests + +```bash +kiota manifest generate +``` From 1598d1da401b8493741720d220dd850f069cd99b Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Wed, 28 Feb 2024 17:25:04 -0300 Subject: [PATCH 07/22] Fixing naming --- specs/cli/config-init.md | 2 +- specs/cli/manifest-add.md | 13 ++++++------- specs/cli/manifest-edit.md | 8 ++++---- specs/cli/manifest-remove.md | 2 +- 4 files changed, 12 insertions(+), 13 deletions(-) diff --git a/specs/cli/config-init.md b/specs/cli/config-init.md index 29efcf548a..7a2a3e93d1 100644 --- a/specs/cli/config-init.md +++ b/specs/cli/config-init.md @@ -7,7 +7,7 @@ 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` or `kiota plugin generate` command could generate a `kiota-config.json` file with values coming from the `kiota client generate` or `kiota plugin generate` commands (if no `kiota-config.json` is present). See [kiota client generate](./client-generate.md) or [kiota plugin generate](./plugin-generate.md) for more information. +> If a project only needs a single API, using `kiota config init` is not mandatory as generating code using the `kiota client generate` or `kiota manifest generate` command could generate a `kiota-config.json` file with values coming from the `kiota client generate` or `kiota manifest generate` commands (if no `kiota-config.json` is present). See [kiota client generate](./client-generate.md) or [kiota manifest generate](./manifest-generate.md) for more information. ## Parameters diff --git a/specs/cli/manifest-add.md b/specs/cli/manifest-add.md index 14ae7bf379..bc313563eb 100644 --- a/specs/cli/manifest-add.md +++ b/specs/cli/manifest-add.md @@ -10,7 +10,7 @@ Every time a plugin manifest is added, a copy of the OpenAPI description file wi An [API Manifest][def] file named `apimanifest-plugins` will be generated (if non existing) or updated (if already existing) in the root folder next to `kiota-config.json`. This file will represent a concatenated surface of all APIs used across plugins. A new hash composed of the Kiota version, the OpenAPI description location and the properties of the plugins will be generated and would trigger an update to the [API Manifest][def]. -Developers can generate `typea` and `apimanifest` plugin manifests. By generating `typea`, two outputs will be generated: a\) the manifest type you have choosen that will be named `{plugin-name}-{type}.json` and b\) an [API Manifest][def] which will be named `{plugin-name}-apimanifest.json` that will include only the information for this specific plugin. `apimanifest` will generate only an API Manifest. +Developers can generate `openai` and `apimanifest` plugin manifests. By generating `openai`, two outputs will be generated: a\) the manifest type you have choosen that will be named `{plugin-name}-{type}.json` and b\) an [API Manifest][def] which will be named `{plugin-name}-apimanifest.json` that will include only the information for this specific plugin. `apimanifest` will generate only an API Manifest. > [!NOTE] > There will be two different [API Manifests][def]. One in the root folder representing a concatenated surface of all APIs and a second one specific to each plugin saved in the choosen output directory. @@ -24,7 +24,7 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | | `--include-path \| -i` | No | /repos/\*\* | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | | `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | -| `--type \| -t` | Yes | typea | The target type of manifest for the generated output files. Possible values are `typea` and `apimanifest`. Defaults to `apimanifest`| +| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| | `--overlayDirectory \| --od` | No | ./overlay/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin manifest. [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. | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | | `--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`. | @@ -35,7 +35,7 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file ## Using `kiota manifest add` ```bash -kiota manifest 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/**" --type typea --output "./generated/plugins/github" +kiota manifest 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/**" --type openai --output "./generated/plugins/github" ``` _The resulting `kiota-config.json` file will look like this:_ @@ -49,7 +49,7 @@ _The resulting `kiota-config.json` file will look like this:_ "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "includePatterns": ["/repos/**"], "excludePatterns": [], - "type": "typea", + "type": "openai", "outputDirectory": "./generated/plugins/github", "overlayDirectory": "./overlays/plugins/github/overlay.yaml" } @@ -57,7 +57,7 @@ _The resulting `kiota-config.json` file will look like this:_ } ``` -_The resulting `github-typea.json` file will look like this:_ +_The resulting `github-openai.json` file will look like this:_ ```jsonc @@ -169,10 +169,9 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l └─generated └─plugins └─graphplugin - └─graphplugin-typeb.json └─graphplugin-apimanifest.json └─github - └─github-typea.json + └─github-openai.json └─github-apimanifest.json └─kiota-config.json └─apimanifest.json diff --git a/specs/cli/manifest-edit.md b/specs/cli/manifest-edit.md index 529ac3ccb7..8ba15ca5dc 100644 --- a/specs/cli/manifest-edit.md +++ b/specs/cli/manifest-edit.md @@ -18,7 +18,7 @@ Once the `kiota-config.json` file and the API Manifest are updated, the code gen | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | | `--include-path \| -i` | No | /repos/\*\* | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | | `--exclude-path \| -e` | No | /repos/{owner}/{repo}/actions/cache/usage | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | -| `--type \| -t` | Yes | typea | The target type of manifest for the generated output files. Possible values are `typea` and `apimanifest`. Defaults to `apimanifest`| +| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| | `--overlayDirectory \| --od` | No | ./overlay/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin manifest. [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. | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | | `--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`. | @@ -43,7 +43,7 @@ _The resulting `kiota-config.json` file will look like this:_ "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "includePatterns": ["/repos/**"], "excludePatterns": ["/repos/{owner}/{repo}/actions/cache/usage"], - "type": "typea", + "type": "openai", "outputDirectory": "./generated/plugins/github", "overlayDirectory": "./overlays/plugins/github/overlay.yaml" } @@ -51,7 +51,7 @@ _The resulting `kiota-config.json` file will look like this:_ } ``` -_The resulting `github-typea.json` file will look like this:_ +_The resulting `github-openai.json` file will look like this:_ ```jsonc @@ -157,7 +157,7 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l └─graphplugin └─graphplugin-apimanifest.json └─github - └─github-typea.json + └─github-openai.json └─github-apimanifest.json └─kiota-config.json └─apimanifest.json diff --git a/specs/cli/manifest-remove.md b/specs/cli/manifest-remove.md index 9f5d405a53..0ea81a5217 100644 --- a/specs/cli/manifest-remove.md +++ b/specs/cli/manifest-remove.md @@ -16,7 +16,7 @@ The command also has one optional parameter, the ability to remove the generated ```bash kiota manifest remove --plugin-name "GitHub" --clean-output ``` -_The resulting `github-apimanifest.json` and `github-typea.json` files will be deleted._ +_The resulting `github-apimanifest.json` and `github-openai.json` files will be deleted._ The resulting `kiota-config.json` file will look like this: From 536b60a62b567fbda8b320e0f7a8b7908d093ee0 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Thu, 7 Mar 2024 15:56:47 -0300 Subject: [PATCH 08/22] Changing naming to manifest --- specs/cli/client-add.md | 2 +- specs/cli/manifest-add.md | 116 ++++++++++++++------------------- specs/cli/manifest-edit.md | 104 ++++++++++++----------------- specs/cli/manifest-generate.md | 14 ++-- specs/cli/manifest-remove.md | 26 ++++---- 5 files changed, 111 insertions(+), 151 deletions(-) diff --git a/specs/cli/client-add.md b/specs/cli/client-add.md index 6f46ee464e..45436d74ea 100644 --- a/specs/cli/client-add.md +++ b/specs/cli/client-add.md @@ -8,7 +8,7 @@ When executing, a new API entry will be added and will use the `--client-name` p 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#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#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 represent a concatenated surface of all APIs used across manifests 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 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). 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. diff --git a/specs/cli/manifest-add.md b/specs/cli/manifest-add.md index bc313563eb..4da8bf1fde 100644 --- a/specs/cli/manifest-add.md +++ b/specs/cli/manifest-add.md @@ -2,40 +2,40 @@ ## Description -`kiota manifest add` allows a developer to add a new plugin manifest 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 manifest with the same name already exists, the command will fail and display an actionnable error message. +`kiota manifest add` allows a developer to add a new manifest 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 `manifests` 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/manifests` folder. If a manifest with the same name already exists, the command will fail and display an actionnable error message. -When executing, a new plugin manifest 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. +When executing, a new manifest entry will be added and will use the `--manifest-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 manifest 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. +Every time a manifest is added, a copy of the OpenAPI description file will be stored in the `./.kiota/manifests` folder. The OpenAPI will be named using the manifest name `{manifest-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-plugins` will be generated (if non existing) or updated (if already existing) in the root folder next to `kiota-config.json`. This file will represent a concatenated surface of all APIs used across plugins. A new hash composed of the Kiota version, the OpenAPI description location and the properties of the plugins 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 next to `kiota-config.json`. This file will represent a concatenated surface of all APIs used across manifests 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]. -Developers can generate `openai` and `apimanifest` plugin manifests. By generating `openai`, two outputs will be generated: a\) the manifest type you have choosen that will be named `{plugin-name}-{type}.json` and b\) an [API Manifest][def] which will be named `{plugin-name}-apimanifest.json` that will include only the information for this specific plugin. `apimanifest` will generate only an API Manifest. +Developers can generate `openai` and `apimanifest` type of manifests. By generating `openai` or `apimanifest`, two outputs will be generated: a\) the manifest type you have choosen that will be named `{manifest-name}-{type}.json` and b\) a sliced OpenAPI description with only the endpoints that matches `--include-path` and `--exclude-path`, if provided. > [!NOTE] -> There will be two different [API Manifests][def]. One in the root folder representing a concatenated surface of all APIs and a second one specific to each plugin saved in the choosen output directory. +> 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 manifest, will be named `{manifest-name}-apimanifest.json` and saved in the choosen output directory when `apimanifest` value is used as the manifest type. -Once the `kiota-config.json` file is generated and the OpenAPI description file is saved locally, the generation will be executed and the manifest will become available. +Once the `kiota-config.json` file is generated and the OpenAPI description file is saved locally, the generation will be executed and the manifest and the sliced OpenAPI description will become available. ## Parameters | Parameters | Required | Example | Description | | -- | -- | -- | -- | -| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `PluginManifest` | +| `--manifest-name \| --pn` | Yes | GitHub | Name of the manifest. Unique within the parent API. Defaults to `Manifest` | | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | -| `--include-path \| -i` | No | /repos/\*\* | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | +| `--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. | | `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | -| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| -| `--overlayDirectory \| --od` | No | ./overlay/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin manifest. [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. | +| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| +| `--overlayDirectory \| --od` | No | ./overlay/manifest/{manifest-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the manifest. [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. | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | -| `--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`. | +| `--output \| -o` | No | ./generated/manifest/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`. | > [!NOTE] -> It is not required to use the CLI to add new manifests. It is possible to add a new plugin manifest by adding a new entry in the `plugins` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-plugin-config.json) for more information. Using `kiota manifest generate --plugin-name myPluginManifest` would be required to generate the manifests. +> It is not required to use the CLI to add new manifests. It is possible to add a new manifest by adding a new entry in the `manifests` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json) for more information. Using `kiota manifest generate --manifest-name myManifest` would be required to generate the manifests. ## Using `kiota manifest add` ```bash -kiota manifest 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/**" --type openai --output "./generated/plugins/github" +kiota manifest add --manifest-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/manifests/github" ``` _The resulting `kiota-config.json` file will look like this:_ @@ -44,14 +44,14 @@ _The resulting `kiota-config.json` file will look like this:_ { "version": "1.0.0", "clients": {...}, //if any - "plugins": { + "manifests": { "GitHub": { "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", - "includePatterns": ["/repos/**"], + "includePatterns": ["/repos/{owner}/{repo}"], "excludePatterns": [], "type": "openai", - "outputDirectory": "./generated/plugins/github", - "overlayDirectory": "./overlays/plugins/github/overlay.yaml" + "outputDirectory": "./generated/manifests/github", + "overlayDirectory": "./overlays/manifests/github/overlay.yaml" } } } @@ -60,7 +60,23 @@ _The resulting `kiota-config.json` file will look like this:_ _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, update and remove repositories.", + "auth": { + "type": "none" + }, + "api": { + "type": "openapi", + "url": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.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:_ @@ -81,26 +97,10 @@ _The resulting `github-apimanifest.json` file will look like this:_ { "method": "PATCH", "uriTemplate": "/repos/{owner}/{repo}" - },, - { - "method": "DELETE", - "uriTemplate": "/repos/{owner}/{repo}" - }, - { - "method": "GET", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts" - }, - { - "method": "GET", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" }, { "method": "DELETE", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" - }, - { - "method": "GET", - "uriTemplate": "/repos/{owner}/{repo}/actions/cache/usage" + "uriTemplate": "/repos/{owner}/{repo}" } ] } @@ -113,15 +113,15 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l ```jsonc { "apiDependencies": { - "GraphPlugin": { - "x-ms-kiotaHash": "1GFCD345RF3DD98...", + "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": [ ... ] + "requests": [ ...] }, - "GitHub": { - "x-ms-kiotaHash": "9EDF8506CB74FE44...", + "GitHub": { //new manifest 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", @@ -133,26 +133,10 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l { "method": "PATCH", "uriTemplate": "/repos/{owner}/{repo}" - },, - { - "method": "DELETE", - "uriTemplate": "/repos/{owner}/{repo}" - }, - { - "method": "GET", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts" - }, - { - "method": "GET", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" }, { "method": "DELETE", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" - }, - { - "method": "GET", - "uriTemplate": "/repos/{owner}/{repo}/actions/cache/usage" + "uriTemplate": "/repos/{owner}/{repo}" } ] } @@ -163,18 +147,16 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l ## File structure ```bash └─.kiota - └─plugins - └─GraphPlugin.yaml - └─GitHub.json + └─manifests + └─GitHub.json # OpenAPI description └─generated - └─plugins - └─graphplugin - └─graphplugin-apimanifest.json + └─manifests └─github - └─github-openai.json - └─github-apimanifest.json + └─github-apimanifest.json # Specific apimanifest + └─github-openai.json #OpenAI manifest + └─sliced-openapi-github.json # Sliced OpenAPI description └─kiota-config.json - └─apimanifest.json + └─apimanifest.json # Single artifact with all APIs info ``` [def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html#section-2.5-3 \ No newline at end of file diff --git a/specs/cli/manifest-edit.md b/specs/cli/manifest-edit.md index 8ba15ca5dc..d111599c30 100644 --- a/specs/cli/manifest-edit.md +++ b/specs/cli/manifest-edit.md @@ -2,11 +2,11 @@ ## Description -`kiota manifest update` allows a developer to edit an existing plugin manifest 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 manifest update` allows a developer to edit an existing manifest in the `kiota-config.json` file. If either the `kiota-config.json` file or if the `--manifest-name` manifest can't be found within the `kiota-config.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 manifest. 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 plugin manifest will be generated and and would trigger an update to the [API Manifest][def] located in the root folder. +When executing, the manifest entry defined by the `--manifest-name` parameter will be modified. All parameters should be supported and the only required one is `--manifest-name`. All others are optional as they would only modify the configuration of the manifest. If the OpenAPI description location changed or any properties of the manifest 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). > [!NOTE] -> There will be two different [API Manifests][def]. One in the root folder representing a concatenated surface of all APIs and a second one specific to each plugin manifest saved in the choosen output directory. +> > 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 manifest, will be named `{manifest-name}-apimanifest.json` and saved in the choosen output directory when `apimanifest` value is used as the manifest 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. @@ -14,22 +14,22 @@ Once the `kiota-config.json` file and the API Manifest are updated, the code gen | Parameters | Required | Example | Description | | -- | -- | -- | -- | -| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `PluginManifest` | +| `--manifest-name \| --pn` | Yes | GitHub | Name of the manifest. Unique within the parent API. Defaults to `Manifest` | | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | -| `--include-path \| -i` | No | /repos/\*\* | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | -| `--exclude-path \| -e` | No | /repos/{owner}/{repo}/actions/cache/usage | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | -| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| -| `--overlayDirectory \| --od` | No | ./overlay/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin manifest. [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. | +| `--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. | +| `--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. | +| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| +| `--overlayDirectory \| --od` | No | ./overlay/manifests/{manifest-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the manifest. [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. | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | -| `--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`. | +| `--output \| -o` | No | ./generated/manifests/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`. | > [!NOTE] -> It is not required to use the CLI to edit plugin manifests. It is possible to edit a plugins by modifying its entry in the `plugins` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-plugin-config.json) for more information. +> It is not required to use the CLI to edit manifests. It is possible to edit a manifest by modifying its entry in the `manifests` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json) for more information. ## Using `kiota manifest edit` ```bash -kiota manifest edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}/actions/cache/usage" +kiota manifest edit --manifest-name "GitHub" --exclude-path "/repos/{owner}/{repo}#DELETE" ``` _The resulting `kiota-config.json` file will look like this:_ @@ -38,14 +38,14 @@ _The resulting `kiota-config.json` file will look like this:_ { "version": "1.0.0", "clients": {...}, //if any - "plugins": { + "manifests": { "GitHub": { "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", - "includePatterns": ["/repos/**"], - "excludePatterns": ["/repos/{owner}/{repo}/actions/cache/usage"], + "includePatterns": ["/repos/{owner}/{repo}"], + "excludePatterns": ["/repos/{owner}/{repo}#DELETE"], "type": "openai", - "outputDirectory": "./generated/plugins/github", - "overlayDirectory": "./overlays/plugins/github/overlay.yaml" + "outputDirectory": "./generated/manifests/github", + "overlayDirectory": "./overlays/manifests/github/overlay.yaml" } } } @@ -54,7 +54,23 @@ _The resulting `kiota-config.json` file will look like this:_ _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": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.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:_ @@ -75,22 +91,6 @@ _The resulting `github-apimanifest.json` file will look like this:_ { "method": "PATCH", "uriTemplate": "/repos/{owner}/{repo}" - },, - { - "method": "DELETE", - "uriTemplate": "/repos/{owner}/{repo}" - }, - { - "method": "GET", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts" - }, - { - "method": "GET", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" - }, - { - "method": "DELETE", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" } ] } @@ -103,15 +103,15 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l ```jsonc { "apiDependencies": { - "GraphPlugin": { - "x-ms-kiotaHash": "1GFCD345RF3DD98...", + "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": [ ... ] + "requests": [ ...] }, "GitHub": { - "x-ms-kiotaHash": "9EDF8506CB74FE44...", + "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", @@ -123,22 +123,6 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l { "method": "PATCH", "uriTemplate": "/repos/{owner}/{repo}" - },, - { - "method": "DELETE", - "uriTemplate": "/repos/{owner}/{repo}" - }, - { - "method": "GET", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts" - }, - { - "method": "GET", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" - }, - { - "method": "DELETE", - "uriTemplate": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" } ] } @@ -149,16 +133,14 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l ## File structure ```bash └─.kiota - └─plugins - └─GraphPlugin.yaml - └─GitHub.json + └─manifests + └─GitHub.json # OpenAPI description └─generated - └─plugins - └─graphplugin - └─graphplugin-apimanifest.json + └─manifests └─github - └─github-openai.json - └─github-apimanifest.json + └─github-apimanifest.json # Specific apimanifest + └─github-openai.json #OpenAI manifest + └─sliced-openapi-github.json # Sliced OpenAPI description └─kiota-config.json └─apimanifest.json ``` diff --git a/specs/cli/manifest-generate.md b/specs/cli/manifest-generate.md index 6f67fdf27b..3962fe342b 100644 --- a/specs/cli/manifest-generate.md +++ b/specs/cli/manifest-generate.md @@ -2,28 +2,28 @@ ## Description -Now that we have a `kiota-config.json` file, all the parameters required to generate the plugin manifests are stored in the file. The `kiota manifest 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 `kiota-config.json` file, all the parameters required to generate the manifests are stored in the file. The `kiota manifest generate` command will read the `kiota-config.json` file and generate the output files for each of the available manifests. -It's also possible to specify for which plugin manifest the output files should be generated. This is useful when there are multiple plugin manifests. The `kiota manifest generate --plugin-name "MyPluginManifest"` command will read the `kiota-config.json` file and generate the code for the specified plugin manifest. If it can't find the specified plugin manifest, it will throw an error. +It's also possible to specify for which manifest the output files should be generated. This is useful when there are multiple plugin manifests. The `kiota manifest generate --manifest-name "MyManifest"` command will read the `kiota-config.json` file and generate the output files for the specified manifest. If it can't find the specified manifest, it will throw an error. -In general cases, the `kiota manifest generate` command will generate the outfiles for all the plugin manifests 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 Manifests and then generate the output files for the specified plugins. +In general cases, the `kiota manifest generate` command will generate the output files for all the manifests 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 Manifests and then generate the output files for the specified manifests. ## Parameters | Parameters | Required | Example | Description | | -- | -- | -- | -- | -| `--plugin-name \| --cn` | No | GitHub | Name of the plugin. Unique within the parent API. | +| `--manifest-name \| --cn` | No | GitHub | Name of the manifest. Unique within the parent API. | | `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. | ## Usage -### Using `kiota manifest generate` for a single plugin manifest +### Using `kiota manifest generate` for a single manifest ```bash -kiota manifest generate --plugin-name "GitHub" +kiota manifest generate --manifest-name "GitHub" ``` -### Using `kiota manifest generate` for all plugin manifests +### Using `kiota manifest generate` for all manifests ```bash kiota manifest generate diff --git a/specs/cli/manifest-remove.md b/specs/cli/manifest-remove.md index 0ea81a5217..50c8e0161a 100644 --- a/specs/cli/manifest-remove.md +++ b/specs/cli/manifest-remove.md @@ -2,19 +2,19 @@ ## Description -`kiota manifest remove` allows a developer to remove an existing plugin manifest 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 manifest. +`kiota manifest remove` allows a developer to remove an existing manifest from the `kiota-config.json` file. The command will remove the entry from the `manifests` section of `kiota-config.json` file. The command has a single required parameters; the name of the manifest. -The command also has one optional parameter, the ability to remove the generated plugin manifest. 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 Manifests). The API Manifests are also updated to remove the dependency from the list of dependencies. +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 manifest configuration. It will also remove the local version of the OpenAPI description file (specified by the `x-ms-kiotaHash` property in the API Manifests). The API Manifests are also updated to remove the dependency from the list of dependencies. | Parameters | Required | Example | Description | | -- | -- | -- | -- | -| `--plugin-name \| --cn` | Yes | GitHub | Name of the plugin | -| `--clean-output \| --co` | No | | Cleans the generated plugin | +| `--manifest-name \| --cn` | Yes | GitHub | Name of the manifest | +| `--clean-output \| --co` | No | | Cleans the generated manifest files | #### Using kiota manifest remove and deleting all the content ```bash -kiota manifest remove --plugin-name "GitHub" --clean-output +kiota manifest remove --manifest-name "GitHub" --clean-output ``` _The resulting `github-apimanifest.json` and `github-openai.json` files will be deleted._ @@ -23,7 +23,7 @@ The resulting `kiota-config.json` file will look like this: ```jsonc { "version": "1.0.0", - "plugins": { } + "manifests": { } } ``` @@ -32,27 +32,23 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l ```jsonc { "apiDependencies": { - "GraphPlugin": { - "x-ms-kiotaHash": "1GFCD345RF3DD98...", + "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": [ ... ] + "requests": [ ...] } } -} //GitHub plugin manifest was removed +} //GitHub manifest was removed ``` ## File structure ```bash / └─.kiota - └─plugins - └─GraphPlugin.yaml └─generated - └─plugins - └─graphplugin - └─graphplugin-apimanifest.json + └─manifests └─github └─kiota-config.json └─apimanifest.json From e14785a16159d0e8001e9e0a40ac366a828f27d0 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Thu, 7 Mar 2024 20:10:33 -0300 Subject: [PATCH 09/22] Add a new manifest scenario and add telemetry to kiota manifest commands. --- specs/cli/manifest-add.md | 23 ++++----- specs/cli/manifest-edit.md | 22 ++++----- specs/cli/manifest-generate.md | 8 +-- specs/cli/manifest-remove.md | 8 +-- specs/scenarios/kiota-config.md | 61 ++++------------------- specs/scenarios/manifests.md | 86 +++++++++++++++++++++++++++++++++ specs/scenarios/telemetry.md | 4 +- specs/schemas/kiota-config.json | 2 +- 8 files changed, 130 insertions(+), 84 deletions(-) create mode 100644 specs/scenarios/manifests.md diff --git a/specs/cli/manifest-add.md b/specs/cli/manifest-add.md index 4da8bf1fde..3eee9c813c 100644 --- a/specs/cli/manifest-add.md +++ b/specs/cli/manifest-add.md @@ -18,16 +18,17 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file ## Parameters -| Parameters | Required | Example | Description | -| -- | -- | -- | -- | -| `--manifest-name \| --pn` | Yes | GitHub | Name of the manifest. Unique within the parent API. Defaults to `Manifest` | -| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | -| `--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. | -| `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | -| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| -| `--overlayDirectory \| --od` | No | ./overlay/manifest/{manifest-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the manifest. [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. | -| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | -| `--output \| -o` | No | ./generated/manifest/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`. | +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--manifest-name \| --mn` | Yes | GitHub | Name of the manifest. Unique within the parent API. Defaults to `Manifest` | No | +| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | No | +| `--search-key \| --sk` | No | apisguru::github.com:api.github.com | The search key used to locate the OpenAPI description. | Yes, without its value | +| `--include-path \| -i` | No | /repos/{owner}/{repo} | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | +| `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | +| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| Yes | +| `--overlayDirectory \| --od` | No | ./overlay/manifest/{manifest-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the manifest. [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/manifest/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 | > [!NOTE] > It is not required to use the CLI to add new manifests. It is possible to add a new manifest by adding a new entry in the `manifests` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json) for more information. Using `kiota manifest generate --manifest-name myManifest` would be required to generate the manifests. @@ -159,4 +160,4 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l └─apimanifest.json # Single artifact with all APIs info ``` -[def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html#section-2.5-3 \ No newline at end of file +[def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html \ No newline at end of file diff --git a/specs/cli/manifest-edit.md b/specs/cli/manifest-edit.md index d111599c30..0050b200ab 100644 --- a/specs/cli/manifest-edit.md +++ b/specs/cli/manifest-edit.md @@ -12,16 +12,16 @@ Once the `kiota-config.json` file and the API Manifest are updated, the code gen ## Parameters -| Parameters | Required | Example | Description | -| -- | -- | -- | -- | -| `--manifest-name \| --pn` | Yes | GitHub | Name of the manifest. Unique within the parent API. Defaults to `Manifest` | -| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | -| `--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. | -| `--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. | -| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| -| `--overlayDirectory \| --od` | No | ./overlay/manifests/{manifest-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the manifest. [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. | -| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | -| `--output \| -o` | No | ./generated/manifests/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`. | +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--manifest-name \| --mn` | Yes | GitHub | Name of the manifest. Unique within the parent API. Defaults to `Manifest` | No | +| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. 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 manifest for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| Yes | +| `--overlayDirectory \| --od` | No | ./overlay/manifests/{manifest-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the manifest. [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/manifests/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 | > [!NOTE] > It is not required to use the CLI to edit manifests. It is possible to edit a manifest by modifying its entry in the `manifests` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json) for more information. @@ -145,4 +145,4 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l └─apimanifest.json ``` -[def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html#section-2.5-3 \ No newline at end of file +[def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html \ No newline at end of file diff --git a/specs/cli/manifest-generate.md b/specs/cli/manifest-generate.md index 3962fe342b..e8f29cd75d 100644 --- a/specs/cli/manifest-generate.md +++ b/specs/cli/manifest-generate.md @@ -10,10 +10,10 @@ In general cases, the `kiota manifest generate` command will generate the output ## Parameters -| Parameters | Required | Example | Description | -| -- | -- | -- | -- | -| `--manifest-name \| --cn` | No | GitHub | Name of the manifest. Unique within the parent API. | -| `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. | +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--manifest-name \| --mn` | No | GitHub | Name of the manifest. Unique within the parent API. | Yes, without its value | +| `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. | Yes | ## Usage diff --git a/specs/cli/manifest-remove.md b/specs/cli/manifest-remove.md index 50c8e0161a..1ce07665b6 100644 --- a/specs/cli/manifest-remove.md +++ b/specs/cli/manifest-remove.md @@ -6,10 +6,10 @@ 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 manifest configuration. It will also remove the local version of the OpenAPI description file (specified by the `x-ms-kiotaHash` property in the API Manifests). The API Manifests are also updated to remove the dependency from the list of dependencies. -| Parameters | Required | Example | Description | -| -- | -- | -- | -- | -| `--manifest-name \| --cn` | Yes | GitHub | Name of the manifest | -| `--clean-output \| --co` | No | | Cleans the generated manifest files | +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--manifest-name \| --mn` | Yes | GitHub | Name of the manifest | No | +| `--clean-output \| --co` | No | | Cleans the generated manifest files | Yes | #### Using kiota manifest remove and deleting all the content diff --git a/specs/scenarios/kiota-config.md b/specs/scenarios/kiota-config.md index d0990d5d9c..4181277ccd 100644 --- a/specs/scenarios/kiota-config.md +++ b/specs/scenarios/kiota-config.md @@ -7,15 +7,14 @@ Kiota generates client code for an API and stores parameters in a kiota-lock.jso - Client code generation is not reproducible if API description changes - Kiota doesn't have an obvious solution for APIs that use multiple security schemes. - Kiota doesn't have an obvious solution for projects utilizing multiple APIs. -- Kiota is currently specialized in client code generation and [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html#section-2.5-3) and it doesn't meet the market expansion for AI scenarios. We have previously described Kiota's approach to managing API dependencies as consistent with the way people manage packages in a project. However, currently our tooling doesn't behave that way. We treat each dependency independently. ## Proposal -We should introduce a new Kiota.config file that holds the input parameters required to generate either the API Client code or AI plugin manifests. 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.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 did consider creating one kiota-config.json file as a peer of the language project file, however, for someone who wants to generate multiple clients in different languages and plugin manifests for an API, 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 kiota-config.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 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. Here is an example of what the kiota-config.json file could look like. @@ -43,16 +42,6 @@ Here is an example of what the kiota-config.json file could look like. "excludePatterns": [], "language": "csharp", "outputPath": "./generated/businessCentral" - }, - "plugins": { - "GitHub": { - "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", - "includePatterns": ["/repos/**"], - "excludePatterns": [], - "type": "typea", - "outputDirectory": "./generated/plugins/github", - "overlayDirectory": "./overlays/plugins/github/overlay.yaml" - } } } } @@ -69,74 +58,42 @@ The [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01. * [kiota client edit](../cli/client-edit.md) * [kiota client generate](../cli/client-generate.md) * [kiota client remove](../cli/client-remove.md) -* [kiota manifest add](../cli/manifest-add.md) -* [kiota manifest edit](../cli/manifest-edit.md) -* [kiota manifest generate](../cli/manifest-generate.md) -* [kiota manifest remove](../cli/manifest-remove.md) ## End-to-end experience -### APIs clients - -- #### Migrate a project that uses Kiota v1.x for API client +### Migrate a project that uses Kiota v1.x for API client ```bash kiota config migrate ``` -- #### Get started to generate an API client +### Get started to generate an API client ```bash kiota client init kiota client add --client-name "GraphClient" --openapi "https://aka.ms/graph/v1.0/openapi.yaml" --language csharp --output "./csharpClient" ``` -- #### Add a second API client +### Add a second API client ```bash kiota client add --clientName "graphPython" --openapi "https://aka.ms/graph/v1.0/openapi.yaml" --language python --outputPath ./pythonClient ``` -- #### Edit an API client +### Edit an API client ```bash kiota client edit --client-name "GraphClient" --exclude-path "/users/$count" ``` -- #### Remove a language and delete the generated code +### Remove a language and delete the generated code ```bash kiota client delete --client=name "graphPython" --clean-output ``` -- #### Generate code for all API clients +### Generate code for all API clients ```bash kiota client generate -``` - -### AI Plugin Manifests - -- #### Add a plugin manifest - -```bash -kiota manifest 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/**" --type typea --output "./generated/plugins/github" -``` - -- #### Edit an AI plugin manifest - -```bash -kiota manifest edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}/actions/cache/usage" -``` - -- #### Remove an AI plugin manifest - -```bash -kiota manifest remove --plugin-name "GitHub" --clean-output -``` - -- #### Generate all AI plugin manifests - -```bash -kiota manifest generate -``` +``` \ No newline at end of file diff --git a/specs/scenarios/manifests.md b/specs/scenarios/manifests.md new file mode 100644 index 0000000000..ebb322c342 --- /dev/null +++ b/specs/scenarios/manifests.md @@ -0,0 +1,86 @@ +# Kiota Manifest 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 [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 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 manifest and OpenAPI document, it can references one or more OpenAPI descriptions 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 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 manifests. Also a `manifests` entry should be added to [Kiota config](kiota-config.md). + +Here is an example of what the kiota-config.json file could look like. + +```jsonc +{ + "version": "1.0.0", + "clients": { ... }, //if any + "manifests": { + "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/manifests/github", + "overlayDirectory": "./overlays/manifests/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 manifest commands: +* [kiota manifest add](../cli/manifest-add.md) +* [kiota manifest edit](../cli/manifest-edit.md) +* [kiota manifest generate](../cli/manifest-generate.md) +* [kiota manifest remove](../cli/manifest-remove.md) + + +## End-to-end experience + +### Add a manifest + +```bash +kiota manifest add --manifest-name "GitHub" --openapi "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json" --include-path "/repos/**" --type typea --output "./generated/manifests/github" +``` + +### Edit a manifest + +```bash +kiota manifest edit --manifest-name "GitHub" --exclude-path "/repos/{owner}/{repo}/actions/cache/usage" +``` + +### Remove a manifest + +```bash +kiota manifest remove --manifest-name "GitHub" --clean-output +``` + +### Generate all manifests + +```bash +kiota manifest generate +``` diff --git a/specs/scenarios/telemetry.md b/specs/scenarios/telemetry.md index fad4f250b0..b29c95315e 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 manifests, it will also be used for developers to create AI manifests. 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 manifest? - 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/kiota-config.json index f0c683d415..70548d447a 100644 --- a/specs/schemas/kiota-config.json +++ b/specs/schemas/kiota-config.json @@ -63,7 +63,7 @@ } } }, - "plugins": { + "manifests": { "type": "object", "patternProperties": { ".*": { From dfea0f96acadd19e2ecf3d49d23beaf886e5b43e Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Thu, 7 Mar 2024 20:14:30 -0300 Subject: [PATCH 10/22] Fixing naming --- specs/scenarios/manifests.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/scenarios/manifests.md b/specs/scenarios/manifests.md index ebb322c342..2d13a7974f 100644 --- a/specs/scenarios/manifests.md +++ b/specs/scenarios/manifests.md @@ -64,13 +64,13 @@ We will provide manifest commands: ### Add a manifest ```bash -kiota manifest add --manifest-name "GitHub" --openapi "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json" --include-path "/repos/**" --type typea --output "./generated/manifests/github" +kiota manifest add --manifest-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/manifests/github" ``` ### Edit a manifest ```bash -kiota manifest edit --manifest-name "GitHub" --exclude-path "/repos/{owner}/{repo}/actions/cache/usage" +kiota manifest edit --manifest-name "GitHub" --exclude-path "/repos/{owner}/{repo}#DELETE" ``` ### Remove a manifest From 5d8a1822675ce5f38408d0d06f8b972b1f93ccc7 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Fri, 8 Mar 2024 16:57:48 -0300 Subject: [PATCH 11/22] Updated naming from manifest to plugin --- specs/cli/client-add.md | 2 +- specs/cli/client-edit.md | 2 +- specs/cli/config-init.md | 2 +- specs/cli/manifest-add.md | 163 ------------------ specs/cli/manifest-generate.md | 30 ---- specs/cli/manifest-remove.md | 55 ------ specs/cli/plugin-add.md | 163 ++++++++++++++++++ .../cli/{manifest-edit.md => plugin-edit.md} | 40 ++--- specs/cli/plugin-generate.md | 30 ++++ specs/cli/plugin-remove.md | 55 ++++++ specs/scenarios/{manifests.md => plugins.md} | 48 +++--- specs/scenarios/telemetry.md | 4 +- specs/schemas/kiota-config.json | 2 +- 13 files changed, 301 insertions(+), 295 deletions(-) delete mode 100644 specs/cli/manifest-add.md delete mode 100644 specs/cli/manifest-generate.md delete mode 100644 specs/cli/manifest-remove.md create mode 100644 specs/cli/plugin-add.md rename specs/cli/{manifest-edit.md => plugin-edit.md} (58%) create mode 100644 specs/cli/plugin-generate.md create mode 100644 specs/cli/plugin-remove.md rename specs/scenarios/{manifests.md => plugins.md} (57%) diff --git a/specs/cli/client-add.md b/specs/cli/client-add.md index 7669ad58d0..c03d727c0a 100644 --- a/specs/cli/client-add.md +++ b/specs/cli/client-add.md @@ -8,7 +8,7 @@ When executing, a new API entry will be added and will use the `--client-name` p 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#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 represent a concatenated surface of all APIs used across manifests 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 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 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]. 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. diff --git a/specs/cli/client-edit.md b/specs/cli/client-edit.md index edd6ceb3a6..eb8d70cfee 100644 --- a/specs/cli/client-edit.md +++ b/specs/cli/client-edit.md @@ -4,7 +4,7 @@ `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. -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 `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). 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. diff --git a/specs/cli/config-init.md b/specs/cli/config-init.md index 7a2a3e93d1..29efcf548a 100644 --- a/specs/cli/config-init.md +++ b/specs/cli/config-init.md @@ -7,7 +7,7 @@ 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` or `kiota manifest generate` command could generate a `kiota-config.json` file with values coming from the `kiota client generate` or `kiota manifest generate` commands (if no `kiota-config.json` is present). See [kiota client generate](./client-generate.md) or [kiota manifest generate](./manifest-generate.md) for more information. +> If a project only needs a single API, using `kiota config init` is not mandatory as generating code using the `kiota client generate` or `kiota plugin generate` command could generate a `kiota-config.json` file with values coming from the `kiota client generate` or `kiota plugin generate` commands (if no `kiota-config.json` is present). See [kiota client generate](./client-generate.md) or [kiota plugin generate](./plugin-generate.md) for more information. ## Parameters diff --git a/specs/cli/manifest-add.md b/specs/cli/manifest-add.md deleted file mode 100644 index 3eee9c813c..0000000000 --- a/specs/cli/manifest-add.md +++ /dev/null @@ -1,163 +0,0 @@ -# kiota manifest add - -## Description - -`kiota manifest add` allows a developer to add a new manifest 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 `manifests` 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/manifests` folder. If a manifest with the same name already exists, the command will fail and display an actionnable error message. - -When executing, a new manifest entry will be added and will use the `--manifest-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 manifest is added, a copy of the OpenAPI description file will be stored in the `./.kiota/manifests` folder. The OpenAPI will be named using the manifest name `{manifest-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 next to `kiota-config.json`. This file will represent a concatenated surface of all APIs used across manifests 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]. - -Developers can generate `openai` and `apimanifest` type of manifests. By generating `openai` or `apimanifest`, two outputs will be generated: a\) the manifest type you have choosen that will be named `{manifest-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 manifest, will be named `{manifest-name}-apimanifest.json` and saved in the choosen output directory when `apimanifest` value is used as the manifest type. - -Once the `kiota-config.json` file is generated and the OpenAPI description file is saved locally, the generation will be executed and the manifest and the sliced OpenAPI description will become available. - -## Parameters - -| Parameters | Required | Example | Description | Telemetry | -| -- | -- | -- | -- | -- | -| `--manifest-name \| --mn` | Yes | GitHub | Name of the manifest. Unique within the parent API. Defaults to `Manifest` | No | -| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | No | -| `--search-key \| --sk` | No | apisguru::github.com:api.github.com | The search key used to locate the OpenAPI description. | Yes, without its value | -| `--include-path \| -i` | No | /repos/{owner}/{repo} | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | -| `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | -| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| Yes | -| `--overlayDirectory \| --od` | No | ./overlay/manifest/{manifest-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the manifest. [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/manifest/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 | - -> [!NOTE] -> It is not required to use the CLI to add new manifests. It is possible to add a new manifest by adding a new entry in the `manifests` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json) for more information. Using `kiota manifest generate --manifest-name myManifest` would be required to generate the manifests. - -## Using `kiota manifest add` - -```bash -kiota manifest add --manifest-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/manifests/github" -``` - -_The resulting `kiota-config.json` file will look like this:_ - -```jsonc -{ - "version": "1.0.0", - "clients": {...}, //if any - "manifests": { - "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/manifests/github", - "overlayDirectory": "./overlays/manifests/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, update and remove repositories.", - "auth": { - "type": "none" - }, - "api": { - "type": "openapi", - "url": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.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) 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 manifest 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 - └─manifests - └─GitHub.json # OpenAPI description - └─generated - └─manifests - └─github - └─github-apimanifest.json # Specific apimanifest - └─github-openai.json #OpenAI manifest - └─sliced-openapi-github.json # Sliced OpenAPI description - └─kiota-config.json - └─apimanifest.json # Single artifact with all APIs 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/manifest-generate.md b/specs/cli/manifest-generate.md deleted file mode 100644 index e8f29cd75d..0000000000 --- a/specs/cli/manifest-generate.md +++ /dev/null @@ -1,30 +0,0 @@ -# kiota manifest generate - -## Description - -Now that we have a `kiota-config.json` file, all the parameters required to generate the manifests are stored in the file. The `kiota manifest generate` command will read the `kiota-config.json` file and generate the output files for each of the available manifests. - -It's also possible to specify for which manifest the output files should be generated. This is useful when there are multiple plugin manifests. The `kiota manifest generate --manifest-name "MyManifest"` command will read the `kiota-config.json` file and generate the output files for the specified manifest. If it can't find the specified manifest, it will throw an error. - -In general cases, the `kiota manifest generate` command will generate the output files for all the manifests 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 Manifests and then generate the output files for the specified manifests. - -## Parameters - -| Parameters | Required | Example | Description | Telemetry | -| -- | -- | -- | -- | -- | -| `--manifest-name \| --mn` | No | GitHub | Name of the manifest. 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 manifest generate` for a single manifest - -```bash -kiota manifest generate --manifest-name "GitHub" -``` - -### Using `kiota manifest generate` for all manifests - -```bash -kiota manifest generate -``` \ No newline at end of file diff --git a/specs/cli/manifest-remove.md b/specs/cli/manifest-remove.md deleted file mode 100644 index 1ce07665b6..0000000000 --- a/specs/cli/manifest-remove.md +++ /dev/null @@ -1,55 +0,0 @@ -# kiota manifest remove - -## Description - -`kiota manifest remove` allows a developer to remove an existing manifest from the `kiota-config.json` file. The command will remove the entry from the `manifests` section of `kiota-config.json` file. The command has a single required parameters; the name of the manifest. - -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 manifest configuration. It will also remove the local version of the OpenAPI description file (specified by the `x-ms-kiotaHash` property in the API Manifests). The API Manifests are also updated to remove the dependency from the list of dependencies. - -| Parameters | Required | Example | Description | Telemetry | -| -- | -- | -- | -- | -- | -| `--manifest-name \| --mn` | Yes | GitHub | Name of the manifest | No | -| `--clean-output \| --co` | No | | Cleans the generated manifest files | Yes | - -#### Using kiota manifest remove and deleting all the content - -```bash -kiota manifest remove --manifest-name "GitHub" --clean-output -``` -_The resulting `github-apimanifest.json` and `github-openai.json` files will be deleted._ - -The resulting `kiota-config.json` file will look like this: - -```jsonc -{ - "version": "1.0.0", - "manifests": { } -} -``` - -_The resulting `apimanifest.json` file (concatenated surface of all APIs) 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 manifest was removed -``` - -## File structure -```bash -/ - └─.kiota - └─generated - └─manifests - └─github - └─kiota-config.json - └─apimanifest.json -``` \ No newline at end of file diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md new file mode 100644 index 0000000000..ea7fef3b62 --- /dev/null +++ b/specs/cli/plugin-add.md @@ -0,0 +1,163 @@ +# kiota plugin add + +## 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. + +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]. + +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. +> [!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 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 + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--plugin-name \| --mn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | +| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | No | +| `--search-key \| --sk` | No | apisguru::github.com:api.github.com | The search key used to locate the OpenAPI description. | Yes, without its value | +| `--include-path \| -i` | No | /repos/{owner}/{repo} | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | +| `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | +| `--type \| -t` | Yes | openai | The target type of plugin for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| Yes | +| `--overlayDirectory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | +| `--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 | + +> [!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. + +## 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 `kiota-config.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", + "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, update and remove 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}" + }, + { + "method": "DELETE", + "uriTemplate": "/repos/{owner}/{repo}" + } + ] + } + } +} +``` + +_The resulting `apimanifest.json` file (concatenated surface of all APIs dependencies) 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 + └─plugins + └─GitHub.json # OpenAPI description + └─generated + └─plugins + └─github + └─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/manifest-edit.md b/specs/cli/plugin-edit.md similarity index 58% rename from specs/cli/manifest-edit.md rename to specs/cli/plugin-edit.md index 0050b200ab..6d97e96291 100644 --- a/specs/cli/manifest-edit.md +++ b/specs/cli/plugin-edit.md @@ -1,12 +1,12 @@ -# kiota manifest edit +# kiota plugin edit ## Description -`kiota manifest update` allows a developer to edit an existing manifest in the `kiota-config.json` file. If either the `kiota-config.json` file or if the `--manifest-name` manifest 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 `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. -When executing, the manifest entry defined by the `--manifest-name` parameter will be modified. All parameters should be supported and the only required one is `--manifest-name`. All others are optional as they would only modify the configuration of the manifest. If the OpenAPI description location changed or any properties of the manifest 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 `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). > [!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 manifest, will be named `{manifest-name}-apimanifest.json` and saved in the choosen output directory when `apimanifest` value is used as the manifest 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 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. @@ -14,22 +14,22 @@ Once the `kiota-config.json` file and the API Manifest are updated, the code gen | Parameters | Required | Example | Description | Telemetry | | -- | -- | -- | -- | -- | -| `--manifest-name \| --mn` | Yes | GitHub | Name of the manifest. Unique within the parent API. Defaults to `Manifest` | No | -| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the manifest. Accepts a URL or a local directory. | Yes, without its value | +| `--plugin-name \| --mn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | +| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | Yes, without its value | | `--include-path \| -i` | No | /repos/{owner}/{repo} | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | | `--exclude-path \| -e` | No | /repos/{owner}/{repo}#DELETE | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | -| `--type \| -t` | Yes | openai | The target type of manifest for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| Yes | -| `--overlayDirectory \| --od` | No | ./overlay/manifests/{manifest-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the manifest. [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 | +| `--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/manifests/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 `kiota-config.json`. Defaults to `./output`. | Yes, without its value | > [!NOTE] -> It is not required to use the CLI to edit manifests. It is possible to edit a manifest by modifying its entry in the `manifests` 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 `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json) for more information. -## Using `kiota manifest edit` +## Using `kiota plugin edit` ```bash -kiota manifest edit --manifest-name "GitHub" --exclude-path "/repos/{owner}/{repo}#DELETE" +kiota plugin edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}#DELETE" ``` _The resulting `kiota-config.json` file will look like this:_ @@ -38,14 +38,14 @@ _The resulting `kiota-config.json` file will look like this:_ { "version": "1.0.0", "clients": {...}, //if any - "manifests": { + "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/manifests/github", - "overlayDirectory": "./overlays/manifests/github/overlay.yaml" + "outputDirectory": "./generated/plugins/github", + "overlayDirectory": "./overlays/plugins/github/overlay.yaml" } } } @@ -65,7 +65,7 @@ _The resulting `github-openai.json` file will look like this:_ }, "api": { "type": "openapi", - "url": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json" + "url": "./sliced-openapi-github.json" }, "logo_url": "https://example.com/logo.png", "contact_email": "githubsupport@example.com", @@ -133,13 +133,13 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l ## File structure ```bash └─.kiota - └─manifests + └─plugins └─GitHub.json # OpenAPI description └─generated - └─manifests + └─plugins └─github - └─github-apimanifest.json # Specific apimanifest - └─github-openai.json #OpenAI manifest + └─github-apimanifest.json # Specific API Manifest + └─github-openai.json #OpenAI Plugin └─sliced-openapi-github.json # Sliced OpenAPI description └─kiota-config.json └─apimanifest.json diff --git a/specs/cli/plugin-generate.md b/specs/cli/plugin-generate.md new file mode 100644 index 0000000000..7b7e553dc5 --- /dev/null +++ b/specs/cli/plugin-generate.md @@ -0,0 +1,30 @@ +# kiota plugin generate + +## 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. + +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. + +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. + +## Parameters + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--plugin-name \| --mn` | 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..e159dcaa11 --- /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 `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. + +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. + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--plugin-name \| --mn` | 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-apiplugin.json` and `github-openai.json` files will be deleted._ + +The resulting `kiota-config.json` file will look like this: + +```jsonc +{ + "version": "1.0.0", + "plugins": { } +} +``` + +_The resulting `apiplugin.json` file (concatenated surface of all APIs) 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 + └─generated + └─plugins + └─github + └─kiota-config.json + └─apiplugin.json +``` \ No newline at end of file diff --git a/specs/scenarios/manifests.md b/specs/scenarios/plugins.md similarity index 57% rename from specs/scenarios/manifests.md rename to specs/scenarios/plugins.md index 2d13a7974f..b268628dcd 100644 --- a/specs/scenarios/manifests.md +++ b/specs/scenarios/plugins.md @@ -1,12 +1,12 @@ -# Kiota Manifest Generation +# 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 [manifest file](https://platform.openai.com/docs/plugins/getting-started/plugin-manifest) that defines relevant metadata information that allows GPT to call an API. +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 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 manifest and OpenAPI document, it can references one or more OpenAPI descriptions as dependencies. +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 descriptions 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. @@ -18,12 +18,12 @@ https://learn.microsoft.com/en-us/semantic-kernel/overview/) as their AI orchest ## 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 Manifests. +- 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 manifests. Also a `manifests` 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 config](kiota-config.md). Here is an example of what the kiota-config.json file could look like. @@ -31,14 +31,14 @@ Here is an example of what the kiota-config.json file could look like. { "version": "1.0.0", "clients": { ... }, //if any - "manifests": { + "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/manifests/github", - "overlayDirectory": "./overlays/manifests/github/overlay.yaml" + "outputDirectory": "./generated/plugins/github", + "overlayDirectory": "./overlays/plugins/github/overlay.yaml" } } } @@ -52,35 +52,41 @@ In addition to managing clients: * [kiota client generate](../cli/client-generate.md) * [kiota client remove](../cli/client-remove.md) -We will provide manifest commands: -* [kiota manifest add](../cli/manifest-add.md) -* [kiota manifest edit](../cli/manifest-edit.md) -* [kiota manifest generate](../cli/manifest-generate.md) -* [kiota manifest remove](../cli/manifest-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 manifest +### Add a plugin ```bash -kiota manifest add --manifest-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/manifests/github" +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 manifest +### Edit a plugin ```bash -kiota manifest edit --manifest-name "GitHub" --exclude-path "/repos/{owner}/{repo}#DELETE" +kiota plugin edit --plugin-name "GitHub" --exclude-path "/repos/{owner}/{repo}#DELETE" ``` -### Remove a manifest +### Remove a plugin ```bash -kiota manifest remove --manifest-name "GitHub" --clean-output +kiota plugin remove --plugin-name "GitHub" --clean-output ``` -### Generate all manifests +### Generate all plugins ```bash -kiota manifest generate +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 b29c95315e..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 and API owners to create code clients that interact with APIs. And with the new commands that generate manifests, it will also be used for developers to create AI manifests. 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 @@ -49,7 +49,7 @@ We should be very careful about the information we collect. Before rolling out t - 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 manifest? +- 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/kiota-config.json index 70548d447a..f0c683d415 100644 --- a/specs/schemas/kiota-config.json +++ b/specs/schemas/kiota-config.json @@ -63,7 +63,7 @@ } } }, - "manifests": { + "plugins": { "type": "object", "patternProperties": { ".*": { From 854c363fd06a134528a662a6a49b3bc5dc11f030 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 20 Mar 2024 11:06:26 -0400 Subject: [PATCH 12/22] - replaces mentions to config by workspace Signed-off-by: Vincent Biret --- .vscode/settings.json | 1 + specs/cli/client-add.md | 22 ++++++++++--------- specs/cli/client-edit.md | 19 ++++++++-------- specs/cli/client-generate.md | 6 ++--- specs/cli/client-remove.md | 10 ++++----- specs/cli/index.md | 4 ++-- specs/cli/plugin-add.md | 20 ++++++++--------- specs/cli/plugin-edit.md | 16 +++++++------- specs/cli/plugin-generate.md | 6 ++--- specs/cli/plugin-remove.md | 6 ++--- .../cli/{config-init.md => workspace-init.md} | 0 ...config-migrate.md => workspace-migrate.md} | 4 ++-- specs/index.md | 8 +++---- .../{kiota-config.md => kiota-workspace.md} | 0 specs/scenarios/plugins.md | 4 ++-- .../{kiota-config.json => workspace.json} | 0 16 files changed, 65 insertions(+), 61 deletions(-) rename specs/cli/{config-init.md => workspace-init.md} (100%) rename specs/cli/{config-migrate.md => workspace-migrate.md} (91%) rename specs/scenarios/{kiota-config.md => kiota-workspace.md} (100%) rename specs/schemas/{kiota-config.json => workspace.json} (100%) 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 From 5eb2627c2e4ff435ffc254ad888e03a757a41d72 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Thu, 21 Mar 2024 12:27:01 -0300 Subject: [PATCH 13/22] replace missing mentions to config by workspace --- specs/cli/workspace-init.md | 16 ++++++++-------- specs/cli/workspace-migrate.md | 18 +++++++++--------- specs/scenarios/kiota-workspace.md | 12 ++++++------ 3 files changed, 23 insertions(+), 23 deletions(-) diff --git a/specs/cli/workspace-init.md b/specs/cli/workspace-init.md index 29efcf548a..7d7902ec6f 100644 --- a/specs/cli/workspace-init.md +++ b/specs/cli/workspace-init.md @@ -1,25 +1,25 @@ -# `kiota config init` +# `kiota workspace init` ## Description -`kiota config init` creates a new kiota-config.json file with the provided parameters. If the file already exists, it should error out and report it to the user. As the file gets created, it should be adding a `version` property with the value of the `kiota-config.json` current schema version. +`kiota workspace init` creates a new workspace.json file with the provided parameters. If the file already exists, it should error out and report it to the user. As the file gets created, it should be adding a `version` property with the value of the `workspace.json` current schema version. -When `kiota config init` is executed, a `kiota-config.json` file would be created in the current directory where the command is being executed. If the user wants to create the file in a different directory, they should use the `--config-file` global parameter. +When `kiota workspace init` is executed, a `workspace.json` file would be created in the current directory where the command is being executed. If the user wants to create the file in a different directory, they should use the `--workspace-file` global parameter. > [!NOTE] -> If a project only needs a single API, using `kiota config init` is not mandatory as generating code using the `kiota client generate` or `kiota plugin generate` command could generate a `kiota-config.json` file with values coming from the `kiota client generate` or `kiota plugin generate` commands (if no `kiota-config.json` is present). See [kiota client generate](./client-generate.md) or [kiota plugin generate](./plugin-generate.md) for more information. +> If a project only needs a single API, using `kiota workspace init` is not mandatory as generating code using the `kiota client generate` or `kiota plugin generate` command could generate a `workspace.json` file with values coming from the `kiota client generate` or `kiota plugin generate` commands (if no `workspace.json` is present). See [kiota client generate](./client-generate.md) or [kiota plugin generate](./plugin-generate.md) for more information. ## Parameters None. -## Using `kiota config init` +## Using `kiota workspace init` ```bash -kiota config init +kiota workspace init ``` -_The resulting `kiota-config.json` file will look like this:_ +_The resulting `workspace.json` file will look like this:_ ```jsonc { @@ -30,5 +30,5 @@ _The resulting `kiota-config.json` file will look like this:_ ## File structure ```bash / - └─kiota-config.json + └─workspace.json ``` \ No newline at end of file diff --git a/specs/cli/workspace-migrate.md b/specs/cli/workspace-migrate.md index 24aa516f69..f2766f491e 100644 --- a/specs/cli/workspace-migrate.md +++ b/specs/cli/workspace-migrate.md @@ -1,6 +1,6 @@ # `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 `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. +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 { @@ -176,5 +176,5 @@ _The resulting `kiota-config.json` file will look like this:_ └─graph_client.py └─kiota-lock.json └─apimanifest.json - └─kiota-config.json + └─workspace.json ``` \ No newline at end of file diff --git a/specs/scenarios/kiota-workspace.md b/specs/scenarios/kiota-workspace.md index 4181277ccd..8635611c80 100644 --- a/specs/scenarios/kiota-workspace.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 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) @@ -64,7 +64,7 @@ The [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01. ### 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 From 95bed89e74267c53fae0de9daa4416dcb115a5fe Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Fri, 22 Mar 2024 10:00:31 -0300 Subject: [PATCH 14/22] fixing some missing changes from kiota-config to workspace --- specs/cli/client-add.md | 2 +- specs/cli/workspace-init.md | 3 ++- specs/cli/workspace-migrate.md | 6 +++--- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/specs/cli/client-add.md b/specs/cli/client-add.md index 90e80a6b22..c960bb549c 100644 --- a/specs/cli/client-add.md +++ b/specs/cli/client-add.md @@ -8,7 +8,7 @@ When executing, a new API entry will be added and will use the `--client-name` p Every time an API client is added, a copy of the OpenAPI description file will be stored in the `./.kiota/clients/{client-name}.yaml|json` folder. The files will be named using the API client name. This will allow the CLI to detect changes in the description and avoid downloading the description again if it hasn't changed. -At the same time, an [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html) file will be generated (if non existing) or edited (if already existing) in the `.kiota` folder next to `workspace.json`. API Manifest represents a snapshot of API dependencies and permissions required to access those APIs. This file will represent a concatenated surface of all APIs used across plugins and clients. Both files, `apimanifest.json` and `workspace.json` will be used to generate the code files. A new hash composed of the Kiota version, the OpenAPI description location and the properties of the manifest will be generated and would trigger an update to the [API Manifest][https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html]. +At the same time, an [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html) file will be generated (if non existing) or edited (if already existing) in the `.kiota` folder next to `workspace.json`. API Manifest represents a snapshot of API dependencies and permissions required to access those APIs. This file will represent a concatenated surface of all APIs used across plugins and clients. Both files, `apimanifest.json` and `workspace.json` will be used to generate the code files. A new hash composed of the Kiota version, the OpenAPI description location and the properties of the client will be generated and would trigger an update to the [API Manifest][https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html]. Once the `workspace.json` file is generated and the OpenAPI description file is saved locally, the code generation will be executed and then the API Manifest would become available. diff --git a/specs/cli/workspace-init.md b/specs/cli/workspace-init.md index 7d7902ec6f..7a196f5026 100644 --- a/specs/cli/workspace-init.md +++ b/specs/cli/workspace-init.md @@ -30,5 +30,6 @@ _The resulting `workspace.json` file will look like this:_ ## File structure ```bash / - └─workspace.json + └─.kiota + └─workspace.json ``` \ No newline at end of file diff --git a/specs/cli/workspace-migrate.md b/specs/cli/workspace-migrate.md index f2766f491e..470bdf07a9 100644 --- a/specs/cli/workspace-migrate.md +++ b/specs/cli/workspace-migrate.md @@ -166,6 +166,8 @@ _The resulting `workspace.json` file will look like this:_ └─.kiota └─definitions └─GraphClient.yaml + └─apimanifest.json + └─workspace.json └─generated └─graph └─csharp @@ -174,7 +176,5 @@ _The resulting `workspace.json` file will look like this:_ └─python └─... # Generated code files └─graph_client.py - └─kiota-lock.json - └─apimanifest.json - └─workspace.json + └─kiota-lock.json ``` \ No newline at end of file From 9beccb25f486da187e6c9c25aa7eb26c09d51842 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Fri, 22 Mar 2024 10:42:44 -0300 Subject: [PATCH 15/22] update specs based on feedback --- specs/cli/client-add.md | 2 +- specs/cli/plugin-add.md | 8 ++++---- specs/cli/plugin-edit.md | 6 +++--- specs/cli/plugin-generate.md | 2 +- specs/cli/plugin-remove.md | 2 +- specs/scenarios/plugins.md | 2 +- 6 files changed, 11 insertions(+), 11 deletions(-) diff --git a/specs/cli/client-add.md b/specs/cli/client-add.md index c960bb549c..87c28860ea 100644 --- a/specs/cli/client-add.md +++ b/specs/cli/client-add.md @@ -2,7 +2,7 @@ ## Description -`kiota client add` allows a developer to add a new API client to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory in current working directory. The command will add a new entry to the `clients` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/clients` folder. If a client with the same name already exists, the command will fail and display an actionable error message. +`kiota client add` allows a developer to add a new API client to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory in current working directory. The command will add a new entry to the `clients` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/clients` folder. If a client or plugin with the same name already exists, the command will fail and display an actionable error message. When executing, a new API entry will be added and will use the `--client-name` parameter as the key for the map. When loading the OpenAPI description, it will store the location of the description in the `descriptionLocation` property. If `--include-path` or `--exclude-path` are provided, they will be stored in the `includePatterns` and `excludePatterns` properties respectively. diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index f814fdda88..4fc97769c5 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -2,7 +2,7 @@ ## Description -`kiota plugin add` allows a developer to add a new plugin to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory under the current working directory. The command will add a new entry to the `plugins` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/plugins` folder. If a plugin with the same name already exists, the command will fail and display an actionable error message. +`kiota plugin add` allows a developer to add a new plugin to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory under the current working directory. The command will add a new entry to the `plugins` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/plugins` folder. If a plugin or client with the same name already exists, the command will fail and display an actionable error message. When executing, a new plugin entry will be added and will use the `--plugin-name` parameter as the key for the map. When loading the OpenAPI description, it will store the location of the description in the `descriptionLocation` property. If `--include-path` or `--exclude-path` are provided, they will be stored in the `includePatterns` and `excludePatterns` properties respectively. @@ -20,13 +20,13 @@ Once the `workspace.json` file is generated and the OpenAPI description file is | Parameters | Required | Example | Description | Telemetry | | -- | -- | -- | -- | -- | -| `--plugin-name \| --mn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | +| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | No | | `--search-key \| --sk` | No | apisguru::github.com:api.github.com | The search key used to locate the OpenAPI description. | Yes, without its value | | `--include-path \| -i` | No | /repos/{owner}/{repo} | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | | `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | | `--type \| -t` | Yes | openai | The target type of plugin for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| Yes | -| `--overlayDirectory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | +| `--overlay-directory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | | `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the location of `workspace.json`. Defaults to `./output`. | Yes, without its value | @@ -50,7 +50,7 @@ _The resulting `workspace.json` file will look like this:_ "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "includePatterns": ["/repos/{owner}/{repo}"], "excludePatterns": [], - "type": "openai", + "type": ["openai"], "outputDirectory": "./generated/plugins/github", "overlayDirectory": "./overlays/plugins/github/overlay.yaml" } diff --git a/specs/cli/plugin-edit.md b/specs/cli/plugin-edit.md index d36eb116c5..acfaab2ee8 100644 --- a/specs/cli/plugin-edit.md +++ b/specs/cli/plugin-edit.md @@ -14,12 +14,12 @@ Once the `workspace.json` file and the API Manifest are updated, the code genera | Parameters | Required | Example | Description | Telemetry | | -- | -- | -- | -- | -- | -| `--plugin-name \| --mn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | +| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | Yes, without its value | | `--include-path \| -i` | No | /repos/{owner}/{repo} | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | | `--exclude-path \| -e` | No | /repos/{owner}/{repo}#DELETE | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | | `--type \| -t` | Yes | openai | The target type of plugin for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| Yes | -| `--overlayDirectory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | +| `--overlay-directory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | | `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the current working directory. Defaults to `./output`. | Yes, without its value | @@ -43,7 +43,7 @@ _The resulting `workspace.json` file will look like this:_ "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "includePatterns": ["/repos/{owner}/{repo}"], "excludePatterns": ["/repos/{owner}/{repo}#DELETE"], - "type": "openai", + "type": ["openai"], "outputDirectory": "./generated/plugins/github", "overlayDirectory": "./overlays/plugins/github/overlay.yaml" } diff --git a/specs/cli/plugin-generate.md b/specs/cli/plugin-generate.md index 033f598658..31f58420c4 100644 --- a/specs/cli/plugin-generate.md +++ b/specs/cli/plugin-generate.md @@ -12,7 +12,7 @@ In general cases, the `kiota plugin generate` command will generate the output f | Parameters | Required | Example | Description | Telemetry | | -- | -- | -- | -- | -- | -| `--plugin-name \| --mn` | No | GitHub | Name of the plugin. Unique within the parent API. | Yes, without its value | +| `--plugin-name \| --pn` | No | GitHub | Name of the plugin. Unique within the parent API. | Yes, without its value | | `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. | Yes | ## Usage diff --git a/specs/cli/plugin-remove.md b/specs/cli/plugin-remove.md index c75f6cf5f3..1df6ba4b4b 100644 --- a/specs/cli/plugin-remove.md +++ b/specs/cli/plugin-remove.md @@ -8,7 +8,7 @@ The command also has one optional parameter, the ability to remove the all gener | Parameters | Required | Example | Description | Telemetry | | -- | -- | -- | -- | -- | -| `--plugin-name \| --mn` | Yes | GitHub | Name of the plugin | No | +| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin | No | | `--clean-output \| --co` | No | | Cleans the generated plugin files | Yes | #### Using kiota plugin remove and deleting all the content diff --git a/specs/scenarios/plugins.md b/specs/scenarios/plugins.md index e24391c3ff..2621f2be65 100644 --- a/specs/scenarios/plugins.md +++ b/specs/scenarios/plugins.md @@ -36,7 +36,7 @@ Here is an example of what the `workspace.json` file could look like. "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "includePatterns": ["/repos/{owner}/{repo}"], "excludePatterns": [], - "type": "openai", + "type": ["openai"], "outputDirectory": "./generated/plugins/github", "overlayDirectory": "./overlays/plugins/github/overlay.yaml" } From b72048d77b420ab380cb3a679b7d9650e662c7cf Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Fri, 22 Mar 2024 18:50:12 -0300 Subject: [PATCH 16/22] Adding information on required fields --- specs/cli/plugin-add.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index 4fc97769c5..d4232c1cf9 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -16,6 +16,29 @@ Developers can generate `openai` and `apimanifest` type of plugins. By generatin Once the `workspace.json` file is generated and the OpenAPI description file is saved locally, the generation will be executed and the plugin and the sliced OpenAPI description will become available. +For `openai` plugins, the mapping should follow [Hidi logic to generate OpenAI Plugin](https://github.com/microsoft/OpenAPI.NET/blob/vnext/src/Microsoft.OpenApi.Hidi/OpenApiService.cs#L748). Requiring fields default as the following: + +| OpenAI field | Default value | +| -- | -- | +| name_for_human | Defaults to the OpenAPI document title. | +| name_for_model | Defaults to `{name_for_human}`. | +| description_for_human | Defaults to the description from the OpenAPI document. If the description is not available, it defaults to `Description for {name_for_human}`. | +| description_for_model | Defaults to `{description_for_human}`. | +| contact_email | Defaults to the contact email from the OpenAPI document. If the contact email is not available, it defaults to 'publisher-email@example.com'. | +| logo_url | Dummy URL? | +| legal_info_url | Dummy URL? | +| | | + +For `apimanifest`, the mapping should follow the [OpenApi.ApiManifest lib map](https://github.com/microsoft/OpenApi.ApiManifest/blob/main/docs/OpenApiToApiManifestMapping.md). Requiring fields are as the following: + +| API Manifest field | Default value | +| -- | -- | +| apiDependencies.Key | Defaults to the plugin name. | +| publisherName | Defaults to the contact name from the OpenAPI document. If the contact name is not available, it defaults to 'publisher-name'. | +| publisherName | Defaults to the contact name from the OpenAPI document. If the contact name is not available, it defaults to 'publisher-name'. | +| publisherEmail | Defaults to the contact email from the OpenAPI document. If the contact email is not available, it defaults to 'publisher-email@example.com'. | +| | | + ## Parameters | Parameters | Required | Example | Description | Telemetry | From b9f253dce36b725c5b59bde1b0848d03a5f37b1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ADsa=20Rissi?= Date: Mon, 25 Mar 2024 12:03:04 -0300 Subject: [PATCH 17/22] Remove duplicated publisherName info Co-authored-by: Vincent Biret --- specs/cli/plugin-add.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index d4232c1cf9..9f087c99d5 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -35,7 +35,6 @@ For `apimanifest`, the mapping should follow the [OpenApi.ApiManifest lib map](h | -- | -- | | apiDependencies.Key | Defaults to the plugin name. | | publisherName | Defaults to the contact name from the OpenAPI document. If the contact name is not available, it defaults to 'publisher-name'. | -| publisherName | Defaults to the contact name from the OpenAPI document. If the contact name is not available, it defaults to 'publisher-name'. | | publisherEmail | Defaults to the contact email from the OpenAPI document. If the contact email is not available, it defaults to 'publisher-email@example.com'. | | | | From e8c0fd1320b8bd780940ba12f144c031757cafb4 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Tue, 26 Mar 2024 11:31:29 -0300 Subject: [PATCH 18/22] Updated openai map to OpenAPI document fields --- specs/cli/plugin-add.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index 9f087c99d5..374bcc2752 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -21,19 +21,19 @@ For `openai` plugins, the mapping should follow [Hidi logic to generate OpenAI P | OpenAI field | Default value | | -- | -- | | name_for_human | Defaults to the OpenAPI document title. | -| name_for_model | Defaults to `{name_for_human}`. | +| 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 `{description_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 | Dummy URL? | -| legal_info_url | Dummy URL? | +| 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 the plugin name. | +| 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'. | | | | From a18633a459e8675d8c47850f751c09ff9de27d51 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Tue, 26 Mar 2024 11:35:29 -0300 Subject: [PATCH 19/22] Removed --searh-key from plugin command --- specs/cli/plugin-add.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index 374bcc2752..f973a8d9b2 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -44,7 +44,6 @@ For `apimanifest`, the mapping should follow the [OpenApi.ApiManifest lib map](h | -- | -- | -- | -- | -- | | `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No | | `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI description in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | No | -| `--search-key \| --sk` | No | apisguru::github.com:api.github.com | The search key used to locate the OpenAPI description. | Yes, without its value | | `--include-path \| -i` | No | /repos/{owner}/{repo} | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | | `--exclude-path \| -e` | No | /advisories | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | | `--type \| -t` | Yes | openai | The target type of plugin for the generated output files. Accepts multiple values. Possible values are `openai` and `apimanifest`. Defaults to `apimanifest`| Yes | From b596a4bfaf9242d9e3bea74c772f0b56f4f91011 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Tue, 26 Mar 2024 12:40:17 -0300 Subject: [PATCH 20/22] Updated folder structure to ./kiota/documents --- specs/cli/client-add.md | 11 +++++----- specs/cli/client-edit.md | 6 +++--- specs/cli/plugin-add.md | 42 +++++++++++++++++++----------------- specs/cli/plugin-edit.md | 20 +++++++++-------- specs/cli/plugin-generate.md | 2 +- specs/cli/plugin-remove.md | 10 ++++----- specs/scenarios/plugins.md | 4 ++-- 7 files changed, 49 insertions(+), 46 deletions(-) diff --git a/specs/cli/client-add.md b/specs/cli/client-add.md index 87c28860ea..f2962a1a59 100644 --- a/specs/cli/client-add.md +++ b/specs/cli/client-add.md @@ -2,11 +2,11 @@ ## Description -`kiota client add` allows a developer to add a new API client to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory in current working directory. The command will add a new entry to the `clients` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/clients` folder. If a client or plugin with the same name already exists, the command will fail and display an actionable error message. +`kiota client add` allows a developer to add a new API client to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory in current working directory. The command will add a new entry to the `clients` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/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) 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]. @@ -18,7 +18,6 @@ Once the `workspace.json` file is generated and the OpenAPI description file is | -- | -- | -- | -- | -- | | `--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 | @@ -109,11 +108,11 @@ _The resulting `apimanifest.json` file will look like this:_ ```bash / └─.kiota - └─clients - └─GraphClient - └─description.yaml └─apimanifest.json └─workspace.json + └─documents + └─GraphClient + └─GraphClient.yaml └─generated └─graph └─csharp diff --git a/specs/cli/client-edit.md b/specs/cli/client-edit.md index 8e533ff474..921e75d78a 100644 --- a/specs/cli/client-edit.md +++ b/specs/cli/client-edit.md @@ -101,11 +101,11 @@ _The resulting `apimanifest.json` file will look like this:_ ```bash / └─.kiota - └─clients - └─GraphClient - └─description.yaml └─apimanifest.json └─workspace.json + └─documents + └─GraphClient + └─GraphClient.yaml └─generated └─graph └─csharp diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index f973a8d9b2..5843aee1f9 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 `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory under the current working directory. The command will add a new entry to the `plugins` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI description is generated and kept in the `.kiota/plugins` folder. If a plugin or client with the same name already exists, the command will fail and display an actionable error message. +`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 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. +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 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. +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 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 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 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 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 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. +> 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 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 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: @@ -43,11 +43,11 @@ For `apimanifest`, the mapping should follow the [OpenApi.ApiManifest lib map](h | 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 description in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | 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 | -| `--overlay-directory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | +| `--overlay \| --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 document. Defaults to no value which uses the OpenAPI document as it is. | Yes, without its value | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | | `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the location of `workspace.json`. Defaults to `./output`. | Yes, without its value | @@ -71,9 +71,9 @@ _The resulting `workspace.json` file will look like this:_ "descriptionLocation": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "includePatterns": ["/repos/{owner}/{repo}"], "excludePatterns": [], - "type": ["openai"], + "type": ["openai", "apimanifest"], "outputDirectory": "./generated/plugins/github", - "overlayDirectory": "./overlays/plugins/github/overlay.yaml" + "overlayDirectory": "./kiota/documents/github/overlay.yaml" } } } @@ -84,16 +84,16 @@ _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.", + "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": "./sliced-openapi-github.json" + "url": "./generated/plugins/github/sliced-openapi-github.json" }, "logo_url": "https://example.com/logo.png", "contact_email": "githubsupport@example.com", @@ -130,7 +130,7 @@ _The resulting `github-apimanifest.json` file will look like this:_ } ``` -_The resulting `apimanifest.json` file (concatenated surface of all APIs dependencies) will look like this:_ +_The resulting `apimanifest.json` file (concatenated surface of all APIs dependencies) in the `./kiota` folder will look like this:_ ```jsonc { @@ -171,14 +171,16 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs depende └─.kiota └─workspace.json └─apimanifest.json # Single artifact with all APIs dependencies info - └─plugins - └─GitHub.json # OpenAPI description + └─documents + └─github + └─GitHub.json # OpenAPI document + └─overlay.json # Overlay to be applied on top of OpenAPI document └─generated └─plugins - └─github + └─github └─github-apimanifest.json # Specific API Manifest └─github-openai.json #OpenAI Plugin - └─sliced-openapi-github.json # Sliced OpenAPI description + └─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 index acfaab2ee8..e63ff0e58e 100644 --- a/specs/cli/plugin-edit.md +++ b/specs/cli/plugin-edit.md @@ -4,9 +4,9 @@ `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 `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). +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 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 `./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. @@ -15,11 +15,11 @@ Once the `workspace.json` file and the API Manifest are updated, the code genera | 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 description in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | Yes, without its value | +| `--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 | -| `--overlay-directory \| --od` | No | ./overlays/plugins/{plugin-name}/overlay.yaml | The location of the overlay file in JSON or YAML format to be used to generate the plugin. [Overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) defines a way of creating documents that contain additional information to be merged with an OpenAPI description. Defaults to no value which uses the OpenAPI description as it is. | Yes, without its value | +| `--overlay \| --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 document. Defaults to no value which uses the OpenAPI document as it is. | Yes, without its value | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | | `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the current working directory. Defaults to `./output`. | Yes, without its value | @@ -98,7 +98,7 @@ _The resulting `github-apimanifest.json` file will look like this:_ } ``` -_The resulting `apimanifest.json` file (concatenated surface of all APIs) will look like this:_ +_The resulting `apimanifest.json` file (concatenated surface of all APIs dependencies) in the `./kiota` folder will look like this:_ ```jsonc { @@ -135,14 +135,16 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs) will l └─.kiota └─workspace.json └─apimanifest.json - └─plugins - └─GitHub.json # OpenAPI description + └─documents + └─github + └─GitHub.json # OpenAPI document + └─overlay.json # Overlay to be applied on top of OpenAPI document └─generated └─plugins - └─github + └─github └─github-apimanifest.json # Specific API Manifest └─github-openai.json #OpenAI Plugin - └─sliced-openapi-github.json # Sliced OpenAPI description + └─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 index 31f58420c4..1ff13924d1 100644 --- a/specs/cli/plugin-generate.md +++ b/specs/cli/plugin-generate.md @@ -6,7 +6,7 @@ Now that we have a `workspace.json` file, all the parameters required to generat 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 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 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 diff --git a/specs/cli/plugin-remove.md b/specs/cli/plugin-remove.md index 1df6ba4b4b..40e1604a16 100644 --- a/specs/cli/plugin-remove.md +++ b/specs/cli/plugin-remove.md @@ -4,7 +4,7 @@ `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. +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 | | -- | -- | -- | -- | -- | @@ -16,18 +16,19 @@ The command also has one optional parameter, the ability to remove the all gener ```bash kiota plugin remove --plugin-name "GitHub" --clean-output ``` -_The resulting `github-apiplugin.json` and `github-openai.json` files will be deleted._ +_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 `apiplugin.json` file (concatenated surface of all APIs) will look like this:_ +_The resulting `apimanifest.json` file (concatenated surface of all APIs dependencies) in the `./kiota` folder will look like this:_ ```jsonc { @@ -48,8 +49,7 @@ _The resulting `apiplugin.json` file (concatenated surface of all APIs) will loo / └─.kiota └─workspace.json + └─apimanifest.json └─generated └─plugins - └─github - └─apiplugin.json ``` \ No newline at end of file diff --git a/specs/scenarios/plugins.md b/specs/scenarios/plugins.md index 2621f2be65..af5b4f8844 100644 --- a/specs/scenarios/plugins.md +++ b/specs/scenarios/plugins.md @@ -6,7 +6,7 @@ Today's AI models can easily generate messages and images for users. While this 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 descriptions as dependencies. +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. @@ -38,7 +38,7 @@ Here is an example of what the `workspace.json` file could look like. "excludePatterns": [], "type": ["openai"], "outputDirectory": "./generated/plugins/github", - "overlayDirectory": "./overlays/plugins/github/overlay.yaml" + "overlayDirectory": "./kiota/documents/github/overlay.yaml" } } } From 95f0adb195935ca686c5a3d326ccda24c0598437 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Tue, 26 Mar 2024 12:45:36 -0300 Subject: [PATCH 21/22] Updated --overlay example --- specs/cli/plugin-add.md | 2 +- specs/cli/plugin-edit.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index 5843aee1f9..2ac5513197 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -47,7 +47,7 @@ For `apimanifest`, the mapping should follow the [OpenApi.ApiManifest lib map](h | `--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 | -| `--overlay \| --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 document. Defaults to no value which uses the OpenAPI document as it is. | Yes, without its value | +| `--overlay \| --od` | No | ./kiota/documents/{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 document. Defaults to no value which uses the OpenAPI document as it is. | Yes, without its value | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | | `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the location of `workspace.json`. Defaults to `./output`. | Yes, without its value | diff --git a/specs/cli/plugin-edit.md b/specs/cli/plugin-edit.md index e63ff0e58e..d12d0b755f 100644 --- a/specs/cli/plugin-edit.md +++ b/specs/cli/plugin-edit.md @@ -19,7 +19,7 @@ Once the `workspace.json` file and the API Manifest are updated, the code genera | `--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 | -| `--overlay \| --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 document. Defaults to no value which uses the OpenAPI document as it is. | Yes, without its value | +| `--overlay \| --od` | No | ./kiota/documents/{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 document. Defaults to no value which uses the OpenAPI document as it is. | Yes, without its value | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | | `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the current working directory. Defaults to `./output`. | Yes, without its value | From b54cb270fc6ee4b3e1f88f1c541a24f3a2e481ad Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Tue, 26 Mar 2024 15:25:59 -0300 Subject: [PATCH 22/22] removing overlays for now --- specs/cli/plugin-add.md | 1 - specs/cli/plugin-edit.md | 1 - 2 files changed, 2 deletions(-) diff --git a/specs/cli/plugin-add.md b/specs/cli/plugin-add.md index 2ac5513197..8c131cc5e4 100644 --- a/specs/cli/plugin-add.md +++ b/specs/cli/plugin-add.md @@ -47,7 +47,6 @@ For `apimanifest`, the mapping should follow the [OpenApi.ApiManifest lib map](h | `--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 | -| `--overlay \| --od` | No | ./kiota/documents/{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 document. Defaults to no value which uses the OpenAPI document as it is. | Yes, without its value | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | | `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the location of `workspace.json`. Defaults to `./output`. | Yes, without its value | diff --git a/specs/cli/plugin-edit.md b/specs/cli/plugin-edit.md index d12d0b755f..588d88e957 100644 --- a/specs/cli/plugin-edit.md +++ b/specs/cli/plugin-edit.md @@ -19,7 +19,6 @@ Once the `workspace.json` file and the API Manifest are updated, the code genera | `--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 | -| `--overlay \| --od` | No | ./kiota/documents/{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 document. Defaults to no value which uses the OpenAPI document as it is. | Yes, without its value | | `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | | `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the current working directory. Defaults to `./output`. | Yes, without its value |