microsoft
/
kiota
зеркало из https://github.com/microsoft/kiota.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Addind API Plugin and Open API extensions in the spec

This commit is contained in:
Maisa Rissi 2024-05-24 17:02:42 -03:00
Родитель 95db74121f
Коммит dc05950576
9 изменённых файлов: 602 добавлений и 56 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

82
specs/cli/plugin-add.md
Просмотреть файл

@ -2,40 +2,67 @@
## Description
`kiota plugin add` allows a developer to add a new plugin to the `workspace.json` file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory under the current working directory. The command will add a new entry to the `plugins` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI document is generated and kept in the `.kiota/documents/{plugin-name}` folder. If a plugin or client with the same name already exists, the command will fail and display an actionable error message.
`kiota plugin add` allows a developer to add a new plugin to the [`workspace.json`](workspace) file. If no `workspace.json` file is found, a new `workspace.json` file would be created in the `.kiota` directory under the current working directory. The command will add a new entry to the `plugins` section of the `workspace.json` file. Once this is done, a local copy of the OpenAPI document is generated and kept in the `.kiota/documents/{plugin-name}` folder. If a plugin or client with the same name already exists, the command will fail and display an actionable error message.
When executing, a new plugin entry will be added and will use the `--plugin-name` parameter as the key for the map. When loading the OpenAPI document, it will store the location of the description in the `descriptionLocation` property. If `--include-path` or `--exclude-path` are provided, they will be stored in the `includePatterns` and `excludePatterns` properties respectively.
Every time a plugin is added, a copy of the OpenAPI document file will be stored in the `./.kiota/documents/{plugin-name}` folder. The OpenAPI will be named using the plugin name `{plugin-name}.json|yaml`. This will allow the CLI to detect changes in the description and avoid downloading the description again if it hasn't changed.
An [API Manifest][def] file named `apimanifest.json` will be generated (if non existing) or updated (if already existing) in the root folder `./kiota` next to `workspace.json`. API Manifest represents a snapshot of API dependencies and permissions required to access those APIs. This file will represent a concatenated surface of all APIs used across plugins and clients. Both files, `apimanifest.json` and `workspace.json` will be used to generate the code files. A new hash composed of the Kiota version, the OpenAPI document location and the properties of the manifest will be generated and would trigger an update to the [API Manifest][def].
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`. This 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 `name_to_be_defined`, `openai` and `apimanifest` type of plugins. By generating plugins, three outputs will be generated: 1\) a sliced OpenAPI document named `{plugin-name}-openapi.json|yaml`, 2\) the plugin type you have chosen and 3\) an [app manifest](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) file named `manifest.json` which conforms with the schema https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema.
Developers can generate `apiplugin`, `openai` and `apimanifest` type of plugins. By generating plugins, three outputs will be generated: 1\) a sliced OpenAPI document named `{plugin-name}-openapi.json|yaml`, 2\) the plugin type you have chosen and 3\) an [app manifest](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) file named `manifest.json` which conforms with the schema https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema.
> [!NOTE]
> In one's solution, there might be two different [API Manifests][def]. The `apimanifest.json` in the `./kiota` folder represents a single artifact surface of all APIs and it will always be generated. The second one, specific to each plugin when providing `--type apimanifest`, will be named `{plugin-name}-apimanifest.json` and saved in the chosen output directory.
> 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 will only be generated when providing `--type apimanifest` when generating a plugin, will be named `{plugin-name}-apimanifest.json` and saved in the chosen output directory.
Once the `workspace.json` file is generated and the OpenAPI document file is saved locally, the generation will be executed and the plugin, the sliced OpenAPI document and the `manifest.json` will become available.
Once the [`workspace.json`](workspace) file is generated and the OpenAPI document file is saved locally, the generation will be executed and the plugin, the sliced OpenAPI document and the `manifest.json` will become available.
### Sliced OpenAPI document
The generated sliced OpenAPI document
will include only the endpoints that matches `--include-path` and `--exclude-path`, if provided, along with their referenced components. All unused components will be removed as well as all OpenAPI extensions (starts with x-) that don't match with our internal documentation of supported extensions in Kiota.
will include only the endpoints that matches `--include-path` and `--exclude-path`, if provided, along with their referenced components. All unused components will be removed as well as all OpenAPI extensions (starts with x-) that don't match with supported extensions in Kiota. See [OpenAPI extensions](../extensions/openapi-extensions.md) supported by Kiota for compreensive list.
### Plugins
For `name_to_be_defined` plugins, the generated plugin should follow the internal document dedicate to it that explains naming, schema and required fields.
#### API Plugin
For `apiplugin`, the generated plugin will be named `{plugin-name}-apiplugin.json` and will follow the schema https://aka.ms/json-schemas/copilot-extensions/v2.1/plugin.schema.json.
For `openai` plugins, the generated plugin will be named `openai-plugins.json` and 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:
Requiring fields default as the following:
| API Plugin field | Default value |
| -- | -- |
| $schema | "https://aka.ms/json-schemas/copilot-extensions/v2.1/plugin.schema.json" |
| schema_version | "v2.1" |
| name_for_human | Defaults to the OpenAPI document title. |
| name_for_model | Defaults to the OpenAPI document title. |
| description_for_human | Defaults to the description from the OpenAPI document. If the description is not available, it defaults to `Description for {name_for_human}`. |
| description_for_model | Defaults to `x-ai-description` extension from the OpenAPI document. If the `x-ai-description` is not available, it defaults to `description_for_human` or `Description for {name_for_human}` if description is not available. |
| namespace | Defaults to `{plugin-name}` |
| 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. |
| functions[n].name | Defaults to `paths[n].operationId` from the OpenAPI document. If the `operationId` is not available or does not match the format ^[a-zA-Z0-9_]*$, Kiota will generate the name based on path and operation. |
| functions[n].description | Defaults to `paths[n].description` from the OpenAPI document. |
| functions[n].parameters | Defaults to `paths[n].parameters` from the OpenAPI document. |
| functions[n].state.reasoning.instructions | Defaults to `x-ai-reasoning-instructions` from the OpenAPI document. If `x-ai-reasoning-instructions` is not available, the `functions[n].state.reasoning.instructions` will not be added in the plugin|
| functions[n].state.responding.instructions | Defaults to `x-ai-responding-instructions` from the OpenAPI document. If `x-ai-responding-instructions` is not available, the `functions[n].state.responding.instructions` will not be added in the plugin|
| | |
See [suno-with-extensions-apiplugins.json example](../examples/suno-with-extensions-apiplugins.json) for reference.
#### OpenAI Plugin
For `openai`, the generated plugin will be named `openai-plugins.json` and the mapping should follow [Hidi logic to generate OpenAI Plugin](https://github.com/microsoft/OpenAPI.NET/blob/vnext/src/Microsoft.OpenApi.Hidi/OpenApiService.cs#L748). Requiring fields default as the following:
| OpenAI field | Default value |
| -- | -- |
| name_for_human | Defaults to the OpenAPI document title. |
| name_for_model | Defaults to the OpenAPI document title. |
| description_for_human | Defaults to the description from the OpenAPI document. If the description is not available, it defaults to `Description for {name_for_human}`. |
| description_for_model | Defaults to x-ai-description extension from the OpenAPI document. If the x-ai-description is not available, it defaults to `description_for_human` or `Description for {name_for_human}`. |
| description_for_model | Defaults to `x-ai-description` extension from the OpenAPI document. If the `x-ai-description` is not available, it defaults to `description_for_human` or `Description for {name_for_human}`. |
| contact_email | Defaults to the contact email from the OpenAPI document. If the contact email is not available, it defaults to 'publisher-email@example.com'. |
| logo_url | Defaults to x-logo extension from the OpenAPI document. If the x-logo is not available, the logo_url will not be added in the plugin. |
| legal_info_url | Defaults to x-legal-info-url extension from the OpenAPI document. If the x-legal-info-url is not availabe, the legal_info_url will not be added in the plugin. |
| 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. |
| | |
See [openai-plugins.json example](../examples/openai-plugins.json) for reference.
#### API Manifest
For `apimanifest`, the generated file will be named `{plugin-name}-apimanifest.json` and 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 |
@ -50,7 +77,7 @@ The app manifest file describes how one's plugin integrates into Microsoft 365 a
For `manifest.json` file, we will:
1. Add a plugin node to the `manifest.json` file if a `manifest.json` file already exists in the output directory.
```json
```jsonc
"copilotExtensions": {
"plugins": [
{
@ -92,7 +119,7 @@ For `manifest.json` file, we will:
"copilotExtensions": {
"plugins": [
{
"id": {plugin-name}
"id": "{plugin-name}",
"file": "<generated_plugin_file>.json"
}
]
@ -110,17 +137,17 @@ For `manifest.json` file, we will:
| `--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 `name_to_be_defined`, `openai` and `apimanifest`.| Yes |
| `--type \| -t` | Yes | openai | The target type of plugin for the generated output files. Accepts multiple values. Possible values are `apiplugin`, `openai` and `apimanifest`.| Yes |
| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes |
| `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the location of `workspace.json`. Defaults to `./output`. | Yes, without its value |
> [!NOTE]
> It is not required to use the CLI to add new plugins. It is possible to add a new plugin by adding a new entry in the `plugins` section of the `workspace.json` file. See the [workspace.json schema](../schemas/workspace.json) for more information. Using `kiota plugin generate --plugin-name myPlugin` would be required to generate the plugins.
> 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 after manually adding them.
## 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"
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 apiplugin, apimanifest --output "./generated/plugins/github"
```
_The resulting `workspace.json` file will look like this:_
@ -142,26 +169,10 @@ _The resulting `workspace.json` file will look like this:_
}
```
_The resulting OpenAI plugin named `openai-plugins.json` will look like this:_
_The resulting API Plugin named `github-apiplugin.json` will look like this:_
```jsonc
{
"schema_version": "v1",
"name_for_human": "GitHub v3 REST API",
"name_for_model": "GitHub v3 REST API",
"description_for_human": "GitHub's v3 REST API",
"description_for_model": "Help the user with managing a GitHub repositories. You can view, update and remove repositories.",
"auth": {
"type": "none"
},
"api": {
"type": "openapi",
"url": "./generated/plugins/github/github-openapi.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 API Manifest named `github-apimanifest.json` will look like this:_
@ -243,8 +254,9 @@ _The resulting API Manifest named `apimanifest.json` in the `./kiota` folder (co
└─github
└─manifest.json # App manifest
└─github-apimanifest.json # Specific API Manifest
└─openai-plugins.json #OpenAI Plugin
└─github-apiplugin.json #API Plugin
└─github-openapi.json # Sliced and augmented OpenAPI document
```
[def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html
[workspace]: (../scenarios/kiota-workspace.md)

23
specs/cli/plugin-edit.md
Просмотреть файл

@ -18,7 +18,7 @@ Once the `workspace.json` file and the API Manifest are updated, the code genera
| `--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 `name_to_be_defined`, `openai` and `apimanifest`.| Yes |
| `--type \| -t` | Yes | openai | The target type of plugin for the generated output files. Accepts multiple values. Possible values are `apiplugin`, `openai` and `apimanifest`.| Yes |
| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes |
| `--output \| -o` | No | ./generated/plugins/github | The output directory or file path for the generated output files. This is relative to the current working directory. Defaults to `./output`. | Yes, without its value |
@ -50,25 +50,11 @@ _The resulting `workspace.json` file will look like this:_
}
```
_The resulting OpenAI plugin named `openai-plugins.json` will look like this:_
_The resulting API Plugin named `github-apiplugin.json` 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": "./github-openapi.json"
},
"logo_url": "https://example.com/logo.png",
"contact_email": "githubsupport@example.com",
"legal_info_url": "http://www.example.com/view-plugin-information"
}
```
@ -141,8 +127,9 @@ _The resulting API Manifest named `apimanifest.json` in the `./kiota` folder (co
└─generated
└─plugins
└─github
└─manifest.json # App manifest
└─github-apimanifest.json # Specific API Manifest
└─openai-plugins.json #OpenAI Plugin
└─github-apiplugin.json #API Plugin
└─github-openapi.json # Sliced and augmented OpenAPI document
```

4
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 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.
The command also has one optional parameter, the ability to remove all generated files. If provided, kiota will delete the folder and its content specified at the `output` 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 plugins are also updated to remove the dependency from the list of dependencies.
| Parameters | Required | Example | Description | Telemetry |
| -- | -- | -- | -- | -- |
@ -16,7 +16,7 @@ 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-apimanifest.json`, `openai-plugins.json` and `github-openapi.json` files will be deleted._
_The resulting `github-apimanifest.json`, `github-apiplugin.json` and `github-openapi.json` files will be deleted._
The resulting `workspace.json` file will look like this:

290
specs/examples/githubsearch-apiplugin.json Normal file
Просмотреть файл

@ -0,0 +1,290 @@
{
"$schema": "https://aka.ms/json-schemas/copilot-extensions/v2.1/plugin.schema.json",
"schema_version": "v2.1",
"name_for_human": "GitHub v3 REST API",
"description_for_human": "GitHub\u0026apos;s v3 REST API.",
"description_for_model": "GitHub\u0026apos;s v3 REST API.",
"logo_url": "https://api.apis.guru/v2/cache/logo/https_twitter.com_github_profile_image.jpeg",
"namespace": "GitHubSearchPlugin",
"capabilities": {
"localization": {}
},
"functions": [
{
"name": "repos/list-public",
"description": "List public repositories",
"parameters": {
"type": "object",
"properties": {
"since": {
"type": "integer",
"description": "A repository ID. Only return repositories with an ID greater than this ID."
}
},
"required": []
}
},
{
"name": "search/code",
"description": "Search code",
"parameters": {
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see [Constructing a search query](https://docs.github.com/rest/reference/search#constructing-a-search-query). See \u0026quot;[Searching code](https://docs.github.com/search-github/searching-on-github/searching-code)\u0026quot; for a detailed list of qualifiers."
},
"sort": {
"type": "string",
"description": "Sorts the results of your query. Can only be \u0060indexed\u0060, which indicates how recently a file has been indexed by the GitHub search infrastructure. Default: [best match](https://docs.github.com/rest/reference/search#ranking-search-results)"
},
"order": {
"type": "string",
"description": "Determines whether the first search result returned is the highest number of matches (\u0060desc\u0060) or lowest number of matches (\u0060asc\u0060). This parameter is ignored unless you provide \u0060sort\u0060.",
"default": "Microsoft.OpenApi.Any.OpenApiString"
},
"per_page": {
"type": "integer",
"description": "The number of results per page (max 100).",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
},
"page": {
"type": "integer",
"description": "Page number of the results to fetch.",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
}
},
"required": [
"q"
]
}
},
{
"name": "search/commits",
"description": "Search commits",
"parameters": {
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see [Constructing a search query](https://docs.github.com/rest/reference/search#constructing-a-search-query). See \u0026quot;[Searching commits](https://docs.github.com/search-github/searching-on-github/searching-commits)\u0026quot; for a detailed list of qualifiers."
},
"sort": {
"type": "string",
"description": "Sorts the results of your query by \u0060author-date\u0060 or \u0060committer-date\u0060. Default: [best match](https://docs.github.com/rest/reference/search#ranking-search-results)"
},
"order": {
"type": "string",
"description": "Determines whether the first search result returned is the highest number of matches (\u0060desc\u0060) or lowest number of matches (\u0060asc\u0060). This parameter is ignored unless you provide \u0060sort\u0060.",
"default": "Microsoft.OpenApi.Any.OpenApiString"
},
"per_page": {
"type": "integer",
"description": "The number of results per page (max 100).",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
},
"page": {
"type": "integer",
"description": "Page number of the results to fetch.",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
}
},
"required": [
"q"
]
}
},
{
"name": "search/issues-and-pull-requests",
"description": "Search issues and pull requests",
"parameters": {
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see [Constructing a search query](https://docs.github.com/rest/reference/search#constructing-a-search-query). See \u0026quot;[Searching issues and pull requests](https://docs.github.com/search-github/searching-on-github/searching-issues-and-pull-requests)\u0026quot; for a detailed list of qualifiers."
},
"sort": {
"type": "string",
"description": "Sorts the results of your query by the number of \u0060comments\u0060, \u0060reactions\u0060, \u0060reactions-\u002B1\u0060, \u0060reactions--1\u0060, \u0060reactions-smile\u0060, \u0060reactions-thinking_face\u0060, \u0060reactions-heart\u0060, \u0060reactions-tada\u0060, or \u0060interactions\u0060. You can also sort results by how recently the items were \u0060created\u0060 or \u0060updated\u0060, Default: [best match](https://docs.github.com/rest/reference/search#ranking-search-results)"
},
"order": {
"type": "string",
"description": "Determines whether the first search result returned is the highest number of matches (\u0060desc\u0060) or lowest number of matches (\u0060asc\u0060). This parameter is ignored unless you provide \u0060sort\u0060.",
"default": "Microsoft.OpenApi.Any.OpenApiString"
},
"per_page": {
"type": "integer",
"description": "The number of results per page (max 100).",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
},
"page": {
"type": "integer",
"description": "Page number of the results to fetch.",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
}
},
"required": [
"q"
]
}
},
{
"name": "search/labels",
"description": "Search labels",
"parameters": {
"type": "object",
"properties": {
"repository_id": {
"type": "integer",
"description": "The id of the repository."
},
"q": {
"type": "string",
"description": "The search keywords. This endpoint does not accept qualifiers in the query. To learn more about the format of the query, see [Constructing a search query](https://docs.github.com/rest/reference/search#constructing-a-search-query)."
},
"sort": {
"type": "string",
"description": "Sorts the results of your query by when the label was \u0060created\u0060 or \u0060updated\u0060. Default: [best match](https://docs.github.com/rest/reference/search#ranking-search-results)"
},
"order": {
"type": "string",
"description": "Determines whether the first search result returned is the highest number of matches (\u0060desc\u0060) or lowest number of matches (\u0060asc\u0060). This parameter is ignored unless you provide \u0060sort\u0060.",
"default": "Microsoft.OpenApi.Any.OpenApiString"
},
"per_page": {
"type": "integer",
"description": "The number of results per page (max 100).",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
},
"page": {
"type": "integer",
"description": "Page number of the results to fetch.",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
}
},
"required": [
"repository_id",
"q"
]
}
},
{
"name": "search/repos",
"description": "Search repositories",
"parameters": {
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see [Constructing a search query](https://docs.github.com/rest/reference/search#constructing-a-search-query). See \u0026quot;[Searching for repositories](https://docs.github.com/articles/searching-for-repositories/)\u0026quot; for a detailed list of qualifiers."
},
"sort": {
"type": "string",
"description": "Sorts the results of your query by number of \u0060stars\u0060, \u0060forks\u0060, or \u0060help-wanted-issues\u0060 or how recently the items were \u0060updated\u0060. Default: [best match](https://docs.github.com/rest/reference/search#ranking-search-results)"
},
"order": {
"type": "string",
"description": "Determines whether the first search result returned is the highest number of matches (\u0060desc\u0060) or lowest number of matches (\u0060asc\u0060). This parameter is ignored unless you provide \u0060sort\u0060.",
"default": "Microsoft.OpenApi.Any.OpenApiString"
},
"per_page": {
"type": "integer",
"description": "The number of results per page (max 100).",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
},
"page": {
"type": "integer",
"description": "Page number of the results to fetch.",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
}
},
"required": [
"q"
]
}
},
{
"name": "search/topics",
"description": "Search topics",
"parameters": {
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see [Constructing a search query](https://docs.github.com/rest/reference/search#constructing-a-search-query)."
},
"per_page": {
"type": "integer",
"description": "The number of results per page (max 100).",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
},
"page": {
"type": "integer",
"description": "Page number of the results to fetch.",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
}
},
"required": [
"q"
]
}
},
{
"name": "search/users",
"description": "Search users",
"parameters": {
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see [Constructing a search query](https://docs.github.com/rest/reference/search#constructing-a-search-query). See \u0026quot;[Searching users](https://docs.github.com/search-github/searching-on-github/searching-users)\u0026quot; for a detailed list of qualifiers."
},
"sort": {
"type": "string",
"description": "Sorts the results of your query by number of \u0060followers\u0060 or \u0060repositories\u0060, or when the person \u0060joined\u0060 GitHub. Default: [best match](https://docs.github.com/rest/reference/search#ranking-search-results)"
},
"order": {
"type": "string",
"description": "Determines whether the first search result returned is the highest number of matches (\u0060desc\u0060) or lowest number of matches (\u0060asc\u0060). This parameter is ignored unless you provide \u0060sort\u0060.",
"default": "Microsoft.OpenApi.Any.OpenApiString"
},
"per_page": {
"type": "integer",
"description": "The number of results per page (max 100).",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
},
"page": {
"type": "integer",
"description": "Page number of the results to fetch.",
"default": "Microsoft.OpenApi.Any.OpenApiInteger"
}
},
"required": [
"q"
]
}
}
],
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "None"
},
"spec": {
"url": "githubsearchplugin-openapi.yml"
},
"run_for_functions": [
"repos/list-public",
"search/code",
"search/commits",
"search/issues-and-pull-requests",
"search/labels",
"search/repos",
"search/topics",
"search/users"
]
}
]
}

17
specs/examples/openai-plugins.json Normal file
Просмотреть файл

@ -0,0 +1,17 @@
{
"schema_version": "v1",
"name_for_human": "GitHub v3 REST API",
"name_for_model": "GitHub v3 REST API",
"description_for_human": "GitHub's v3 REST API",
"description_for_model": "Help the user with managing a GitHub repositories. You can view, update and remove repositories.",
"auth": {
"type": "none"
},
"api": {
"type": "openapi",
"url": "github-openapi.json"
},
"logo_url": "https://example.com/logo.png",
"contact_email": "githubsupport@example.com",
"legal_info_url": "http://www.example.com/view-plugin-information"
}

53
specs/examples/suno-openapi-with-extensions.yaml Normal file
Просмотреть файл

@ -0,0 +1,53 @@
openapi: 3.0.0
info:
title: Suno
description: Create any song you want based on a description
version: 1.0.0
contact:
email: ionutro@microsoft.com
x-logo:
url: https://w7.pngwing.com/pngs/208/848/png-transparent-musical-note-logo-clef-music-logo-design-other-text-musical-composition.png
x-ai-description: Suno is a tool that can generate songs based on a description. The user provides a description of the song they want to create, and Suno generates the song lyrics. Suno is a fun and creative way to create songs for any occasion.
x-legal-info-url": https://app.suno.ai/legal
x-privacy-policy-url": https://app.suno.ai/privacy
paths:
/createSong:
post:
summary: Create a song given the user preferences
operationId: createSong
x-ai-reasoning-instructions:
- 'Is the user requesting to create a song which would warrant the "Parental Advisory Explicit Content" label (e.g., topics about sex, politics, violence, self-harm, hate speech, coercion, etc.)? If so, I **must** invoke withdraw() and end the conversation.'
- "Is the user requesting to create a haiku, poem, lyric, tune, melody, jingle, verse, sonnet, or something other than a song? If so, I **must not** invoke createSong(**params)."
- "Is the user requesting to create a song on a safe and innocuous topic? If so, invoke createSong(**params)."
- "If createSong(**params) is invoked already in this turn, I **will** not invoke the same tool again."
- "Here are the parameters"
- "topic(string, required): The requested song description, e.g., a country song about Thanksgiving, in the user's language"
x-ai-responding-instructions:
- "The response to the user is generated asynchronously therefore I **SHOULD NOT** generate my own song or provide links or lyrics based on this tool's output. I can just let the user know their song will be available shortly and **stop responding** for that turn."
- "I **should not** respond with either sample or full form of lyrics to the song because the song created by createSong(**params) is shown to the user directly along with the lyrics."
- "If createSong(**params) was not invoked because the service was overloaded or the user reached their invocation limit, I **must** tell the user they can visit the https://app.suno.ai website to create more songs and display the link using Markdown syntax."
- "I **shall** tell the user they can visit the https://app.suno.ai website to create more songs and display the link using Markdown syntax."
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
description: The requested song description, e.g., a country song about Thanksgiving
responses:
"200":
description: A Song object
content:
application/json:
schema:
type: object
properties:
lyrics:
type: string
description: The generated song
title:
type: string
description: The title of the song

51
specs/examples/suno-with-extensions-apiplugin.json Normal file
Просмотреть файл

@ -0,0 +1,51 @@
{
"$schema": "https://aka.ms/json-schemas/copilot-extensions/v2.1/plugin.schema.json",
"schema_version": "v2.1",
"name_for_human": "Suno",
"description_for_human": "Create any song you want based on a description",
"description_for_model": "Suno is a tool that can generate songs based on a description. The user provides a description of the song they want to create, and Suno generates the song lyrics. Suno is a fun and creative way to create songs for any occasion.",
"contact_email": "ionutro@microsoft.com",
"namespace": "sunoWithExtensions",
"capabilities": {
"localization": {}
},
"functions": [
{
"name": "createSong",
"description": "Create a song given the user preferences",
"states": {
"reasoning": {
"instructions": [
"Is the user requesting to create a song which would warrant the \u0026quot;Parental Advisory Explicit Content\u0026quot; label (e.g., topics about sex, politics, violence, self-harm, hate speech, coercion, etc.)? If so, I **must** invoke withdraw() and end the conversation.",
"Is the user requesting to create a haiku, poem, lyric, tune, melody, jingle, verse, sonnet, or something other than a song? If so, I **must not** invoke createSong(**params).",
"Is the user requesting to create a song on a safe and innocuous topic? If so, invoke createSong(**params).",
"If createSong(**params) is invoked already in this turn, I **will** not invoke the same tool again.",
"Here are the parameters"
]
},
"responding": {
"instructions": [
"The response to the user is generated asynchronously therefore I **SHOULD NOT** generate my own song or provide links or lyrics based on this tool\u0026apos;s output. I can just let the user know their song will be available shortly and **stop responding** for that turn.",
"I **should not** respond with either sample or full form of lyrics to the song because the song created by createSong(**params) is shown to the user directly along with the lyrics.",
"If createSong(**params) was not invoked because the service was overloaded or the user reached their invocation limit, I **must** tell the user they can visit the https://app.suno.ai website to create more songs and display the link using Markdown syntax.",
"I **shall** tell the user they can visit the https://app.suno.ai website to create more songs and display the link using Markdown syntax."
]
}
}
}
],
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "None"
},
"spec": {
"url": "suno-openapi-with-extensions.yaml"
},
"run_for_functions": [
"createSong"
]
}
]
}

130
specs/extensions/openapi-extensions.md Normal file
Просмотреть файл

@ -0,0 +1,130 @@
# OpenAPI Extensions
[OpenAPI extensions](https://spec.openapis.org/oas/v3.0.3#specification-extensions) are custom properties that can be used to describe extra functionality that is not covered by the standard OpenAPI Specification.
Kiota supports OpenAPI extensions to help users extend OpenAPI documents to customize and augment the generated files.
## Generic extensions
[x-logo](#x-logo)
[x-legal-info-url](#x-legal-info-url)
[x-privacy-info-url](#x-privacy-info-url)
## Plugin Specific Extensions
[x-ai-description](#x-ai-description)
[x-ai-reasoning-instructions](#x-ai-reasoning-instructions)
[x-ai-responding-instructions](#x-ai-responding-instructions)
## x-logo
Specifies the custom logo image.
Applies to: Info
```yaml
openapi: 3.0.0
info:
title: Title
description: Description
version: 1.0.0
x-logo:
url: https://github.com/MyPlugin/icons/color.png
```
## x-legal-info-url
Specifies the link to to a document containing the terms of service.
Applies to: Info
```yaml
openapi: 3.0.0
info:
title: Title
description: Description
version: 1.0.0
x-legal-info-url: https://example.com/legal
```
## x-privacy-info-url
Specifies the link to the document containing the privacy policy.
Applies to: Info
```yaml
openapi: 3.0.0
info:
title: Title
description: Description
version: 1.0.0
x-privacy-info-url: https://example.com/privacy
```
## x-ai-description
Specifies the description for the plugin that will be provided to the model. This description should describe what the plugin is for, and in what circumstances its functions are relevant. Max size 2048 caracters.
Applies to: Info
```yaml
openapi: 3.0.0
info:
title: Title
description: Description
version: 1.0.0
x-ai-description: Suno is a tool that can generate songs based on a description. The user provides a description of the song they want to create, and Suno generates the song lyrics. Suno is a fun and creative way to create songs for any occasion.
```
## x-ai-reasoning-instructions
Specifies instructions for when a specific function is invoked when the orchestrator is in the resoning state.
Reasoning state corresponds to an orchestrator state when the model can call functions and do computations.
Applies to: Operations
```yaml
openapi: 3.0.0
info:
title: Title
description: Description
version: 1.0.0
paths:
/createSong:
post:
summary: Create a song given the user preferences
operationId: createSong
x-ai-reasoning-instructions:
- 'Is the user requesting to create a song which would warrant the "Parental Advisory Explicit Content" label (e.g., topics about sex, politics, violence, self-harm, hate speech, coercion, etc.)? If so, I **must** invoke withdraw() and end the conversation.'
- "Is the user requesting to create a haiku, poem, lyric, tune, melody, jingle, verse, sonnet, or something other than a song? If so, I **must not** invoke createSong(**params)."
- "Is the user requesting to create a song on a safe and innocuous topic? If so, invoke createSong(**params)."
- "If createSong(**params) is invoked already in this turn, I **will** not invoke the same tool again."
- "Here are the parameters"
- "topic(string, required): The requested song description, e.g., a country song about Thanksgiving, in the user's language"
```
## x-ai-responding-instructions
Specifies instructions for when a specific function is invoked when the orchestrator is in the responding state.
Responding state corresponds to an orchestrator state when the model can generate text that will be shown to the user. In this state the model cannot invoke functions.
Applies to: Operations
```yaml
openapi: 3.0.0
info:
title: Title
description: Description
version: 1.0.0
paths:
/createSong:
post:
summary: Create a song given the user preferences
operationId: createSong
x-ai-responding-instructions:
- "The response to the user is generated asynchronously therefore I **SHOULD NOT** generate my own song or provide links or lyrics based on this tool's output. I can just let the user know their song will be available shortly and **stop responding** for that turn."
- "I **should not** respond with either sample or full form of lyrics to the song because the song created by createSong(**params) is shown to the user directly along with the lyrics."
- "If createSong(**params) was not invoked because the service was overloaded or the user reached their invocation limit, I **must** tell the user they can visit the https://app.suno.ai website to create more songs and display the link using Markdown syntax."
- "I **shall** tell the user they can visit the https://app.suno.ai website to create more songs and display the link using Markdown syntax."
```

8
specs/index.md
Просмотреть файл

@ -8,6 +8,10 @@ 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 plugin add](./cli/plugin-add.md)
* [kiota plugin edit](./cli/plugin-edit.md)
* [kiota plugin remove](./cli/plugin-remove.md)
* [kiota plugin generate](./cli/plugin-generate.md)
* [kiota workspace init](./cli/workspace-init.md)
* [kiota workspace migrate](./cli/workspace-migrate.md)
* [kiota download](./cli/download.md)
@ -17,11 +21,13 @@ This repository contains the specifications for the Kiota project. The goal of t
* [kiota search](./cli/search.md)
* [kiota show](./cli/show.md)
## Extension
## OpenAPI Extensions
* [OpenAPI extensions](./extensions/openapi-extensions.md)
## Scenarios
* [Kiota Config](./scenarios/kiota-workspace.md)
* [Plugins](./scenarios/plugins.md)
* [Telemetry](./scenarios/telemetry.md)
## Schemas