From 5d8a1822675ce5f38408d0d06f8b972b1f93ccc7 Mon Sep 17 00:00:00 2001 From: Maisa Rissi Date: Fri, 8 Mar 2024 16:57:48 -0300 Subject: [PATCH] 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": { ".*": {