Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove manifest.json from Kiota generation #5175

Merged
merged 2 commits into from
Aug 16, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 3 additions & 64 deletions specs/cli/plugin-add.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ Every time a plugin is added, a copy of the OpenAPI document file will be stored

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 `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).
Developers can generate `apiplugin`, `openai` and `apimanifest` type of plugins. By generating plugins, two outputs will be generated: 1\) a sliced OpenAPI document named `{plugin-name}-openapi.json|yaml` and 2\) the plugin type you have chosen.
> [!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 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.
> 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 in your solution and it will always be generated. The second one will only be generated when providing `kiota plugin add --type apimanifest` when generating a plugin and will be named `{plugin-name}-apimanifest.json` and saved in the chosen output directory.

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.
Once the [`workspace.json`](workspace) file is generated and the OpenAPI document file is saved locally, the generation will be executed and the plugin and the sliced OpenAPI document will become available.

### Sliced OpenAPI document

Expand Down Expand Up @@ -77,66 +77,6 @@ For `apimanifest`, the generated file will be named `{plugin-name}-apimanifest.j
| publisherEmail | Defaults to the contact email from the OpenAPI document. If the contact email is not available, it defaults to `[email protected]`. |
| | |

### App manifest

The app manifest file describes how one's plugin integrates into Microsoft 365 and it's not related to plugin types. App manifests are required for [publishing apps to Microsoft 365 app stores](https://learn.microsoft.com/en-us/partner-center/marketplace/checklist#step-3-check-that-your-manifest-is-compliant).
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.

```jsonc
"copilotExtensions": {
"plugins": [
{
"id": "{plugin-name}",
"file": "<generated_plugin_file>.json"
}
]
}
```

2. If a `plugins` node already exists and there is no plugin with the same `id`, add the new plugin information. If the `id` already exists, replace the current content.
3. If there is no `manifest.json` file, we should create a basic manifest with only required information as the following example:

```jsonc
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
"manifestVersion": "devPreview",
"version": "1.0.0",
"id": "<generated_GUID>",
"developer": {
"name": "<Defaults to `contact.name` from the OpenAPI document. If the `contact.name` is not available, it defaults to `Kiota Generator, Inc.`>",
"websiteUrl": "<Defaults to `contact.url` from the OpenAPI document. If the `contact.url` is not available, it defaults to `https://www.example.com/contact/`>",
"privacyUrl": "<Defaults to `x-privacy-policy-url` extension from the OpenAPI document. If the `x-privacy-policy-url` is not available, it defaults to `https://www.example.com/privacy/`>",
"termsOfUseUrl": "<Defaults to `termsOfService` from the OpenAPI document. If the `termsOfService` is not available, it defaults to `https://www.example.com/terms/`>"
},
"packageName": "com.microsoft.kiota.plugin.<pluginame>",
"name": {
"short": "<plugin_name>",
"full": "API Plugin <plugin_name> for <OpenAPI document title>"
},
"description": {
"short": "API Plugin for <description from the OpenAPI document>. If the description is not available, it defaults to `API Plugin for <OpenAPI document title>`",
"full": "API Plugin for <description from the OpenAPI document>. If the description is not available, it defaults to `API Plugin for <OpenAPI document title>`"
},
"icons": {
"color": "color.png", //we could default it to a color version of Kiota logo 192x192 pixels where the icon symbol is 96x96 pixels or just use the same as [Teams Toolkit](https://github.com/OfficeDev/TeamsFx/blob/dev/templates/js/workflow/appPackage/color.png)
"outline": "outline.png" //we could default it to an outline Kiota icon 32x32 pixels or just use the same as [Teams Toolkit](https://github.com/OfficeDev/TeamsFx/blob/dev/templates/js/workflow/appPackage/outline.png).
},
"accentColor": "#FFFFFF", //always white
"copilotExtensions": {
"plugins": [
{
"id": "{plugin-name}",
"file": "<generated_plugin_file>.json"
}
]
}
}
```

4. [Validate](https://learn.microsoft.com/en-us/office/dev/add-ins/testing/troubleshoot-manifest) the generated `manifest.json` file.

## Parameters

| Parameters | Required | Example | Description | Telemetry |
Expand Down Expand Up @@ -303,7 +243,6 @@ _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
└─github-apiplugin.json #API Plugin
└─github-openapi.json # Sliced and augmented OpenAPI document
Expand Down
12 changes: 6 additions & 6 deletions specs/cli/plugin-edit.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# kiota plugin edit

## Description
## Description

`kiota plugin update` allows a developer to edit an existing plugin in the `workspace.json` file. If either the `workspace.json` file or if the `--plugin-name` plugin can't be found within the `workspace.json` file, the command should error out and let the developer know.

When executing, the plugin entry defined by the `--plugin-name` parameter will be modified. All parameters should be supported and the only required one is `--plugin-name`. All others are optional as they would only modify the configuration of the plugin. If the OpenAPI document location changed or any properties of the plugin entry in `workspace.json`, a new hash composed of the Kiota version, the OpenAPI document location and the properties of the manifest will be generated and and would trigger an update to the [API Manifest][def] located in the root folder (the).
> [!NOTE]
> [!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.

Once the `workspace.json` file and the API Manifest are updated, the code generation will be executed based on the newly updated API client configuration.
Expand All @@ -15,14 +15,14 @@ Once the `workspace.json` file and the API Manifest are updated, the code genera
| Parameters | Required | Example | Description | Telemetry |
| -- | -- | -- | -- | -- |
| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin. Unique within the parent API. Defaults to `Plugin` | No |
| `--openapi \| -d` | Yes | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json | The location of the OpenAPI document in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | Yes, without its value |
| `--openapi \| -d` | Yes | <https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json> | The location of the OpenAPI document in JSON or YAML format to use to generate the plugin. Accepts a URL or a local directory. | Yes, without its value |
| `--include-path \| -i` | No | /repos/{owner}/{repo} | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value |
| `--exclude-path \| -e` | No | /repos/{owner}/{repo}#DELETE | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value |
| `--type \| -t` | Yes | openai | The target type of plugin for the generated output files. Accepts multiple values. Possible values are `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 |

> [!NOTE]
> [!NOTE]
> It is not required to use the CLI to edit plugins. It is possible to edit a plugin by modifying its entry in the `plugins` section of the `workspace.json` file. See the [workspace.json schema](../schemas/workspace.json) for more information.

## Using `kiota plugin edit`
Expand Down Expand Up @@ -151,6 +151,7 @@ _The resulting API Manifest named `apimanifest.json` in the `./kiota` folder (co
```

## File structure

```bash
└─.kiota
└─workspace.json
Expand All @@ -162,10 +163,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
└─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
[def]: https://www.ietf.org/archive/id/draft-miller-api-manifest-01.html
4 changes: 2 additions & 2 deletions specs/cli/plugin-generate.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Description

Now that we have a `workspace.json` file, all the parameters required to generate the plugins are stored in the file. The `kiota plugin generate` command will read the `workspace.json` file and generate the output files for each of the available plugins.
Now that we have a `workspace.json` file, all the parameters required to generate the plugins are stored in the file. The `kiota plugin generate` command will read the `workspace.json` file and generate the output files for each of the available plugins.

It's also possible to specify for which plugin the output files should be generated. This is useful when there are multiple plugin plugins. The `kiota plugin generate --plugin-name "Myplugin"` command will read the `workspace.json` file and generate the output files for the specified plugin. If it can't find the specified plugin, it will throw an error.

Expand All @@ -27,4 +27,4 @@ kiota plugin generate --plugin-name "GitHub"

```bash
kiota plugin generate
```
```
6 changes: 4 additions & 2 deletions specs/cli/plugin-remove.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Description

`kiota plugin remove` allows a developer to remove an existing plugin from the `workspace.json` file. The command will remove the entry from the `plugins` section of `workspace.json` file. The command has a single required parameters; the name of the plugin.
`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 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.

Expand All @@ -11,11 +11,12 @@ The command also has one optional parameter, the ability to remove all generated
| `--plugin-name \| --pn` | Yes | GitHub | Name of the plugin | No |
| `--clean-output \| --co` | No | | Cleans the generated plugin files | Yes |

#### Using kiota plugin remove and deleting all the content
### Using kiota plugin remove and deleting all the content

```bash
kiota plugin remove --plugin-name "GitHub" --clean-output
```

_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:
Expand Down Expand Up @@ -45,6 +46,7 @@ _The resulting `apimanifest.json` file (concatenated surface of all APIs depende
```

## File structure

```bash
/
└─.kiota
Expand Down
Loading