Skip to content

Commit

Permalink
replace missing mentions to config by workspace
Browse files Browse the repository at this point in the history
  • Loading branch information
maisarissi committed Mar 21, 2024
1 parent 854c363 commit 5eb2627
Show file tree
Hide file tree
Showing 3 changed files with 23 additions and 23 deletions.
16 changes: 8 additions & 8 deletions specs/cli/workspace-init.md
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
# `kiota config init`
# `kiota workspace init`

## Description

`kiota config init` creates a new kiota-config.json file with the provided parameters. If the file already exists, it should error out and report it to the user. As the file gets created, it should be adding a `version` property with the value of the `kiota-config.json` current schema version.
`kiota workspace init` creates a new workspace.json file with the provided parameters. If the file already exists, it should error out and report it to the user. As the file gets created, it should be adding a `version` property with the value of the `workspace.json` current schema version.

When `kiota config init` is executed, a `kiota-config.json` file would be created in the current directory where the command is being executed. If the user wants to create the file in a different directory, they should use the `--config-file` global parameter.
When `kiota workspace init` is executed, a `workspace.json` file would be created in the current directory where the command is being executed. If the user wants to create the file in a different directory, they should use the `--workspace-file` global parameter.

> [!NOTE]
> If a project only needs a single API, using `kiota config init` is not mandatory as generating code using the `kiota client generate` or `kiota plugin generate` command could generate a `kiota-config.json` file with values coming from the `kiota client generate` or `kiota plugin generate` commands (if no `kiota-config.json` is present). See [kiota client generate](./client-generate.md) or [kiota plugin generate](./plugin-generate.md) for more information.
> If a project only needs a single API, using `kiota workspace init` is not mandatory as generating code using the `kiota client generate` or `kiota plugin generate` command could generate a `workspace.json` file with values coming from the `kiota client generate` or `kiota plugin generate` commands (if no `workspace.json` is present). See [kiota client generate](./client-generate.md) or [kiota plugin generate](./plugin-generate.md) for more information.
## Parameters

None.

## Using `kiota config init`
## Using `kiota workspace init`

```bash
kiota config init
kiota workspace init
```

_The resulting `kiota-config.json` file will look like this:_
_The resulting `workspace.json` file will look like this:_

```jsonc
{
Expand All @@ -30,5 +30,5 @@ _The resulting `kiota-config.json` file will look like this:_
## File structure
```bash
/
└─kiota-config.json
└─workspace.json
```
18 changes: 9 additions & 9 deletions specs/cli/workspace-migrate.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# `kiota workspace migrate`

This command is valuable in cases where a code base was created with Kiota v1.0 and needs to be migrated to the latest version of Kiota. The `kiota config migrate` command will identify and locate the closest `workspace.json` file available. If a file can't be found, it would initialize a new `workspace.json` file. Then, it would identify all `kiota-lock.json` files that are within this folder structure and add each of them to the `workspace.json` file. Adding the clients to the `workspace.json` file would not trigger the generation as it only affects the `workspace.json` file. The `kiota client generate` command would need to be executed to generate the code for the clients.
This command is valuable in cases where a code base was created with Kiota v1.0 and needs to be migrated to the latest version of Kiota. The `kiota workspace migrate` command will identify and locate the closest `workspace.json` file available. If a file can't be found, it would initialize a new `workspace.json` file. Then, it would identify all `kiota-lock.json` files that are within this folder structure and add each of them to the `workspace.json` file. Adding the clients to the `workspace.json` file would not trigger the generation as it only affects the `workspace.json` file. The `kiota client generate` command would need to be executed to generate the code for the clients.

The API manifest won't contain any request after the migration since it could lead to misalignments between the generated client and the reported requests if the description has changed between the initial generation of the client and the migration. To get the requests populated, the user will need to use the generate command.

Expand All @@ -13,7 +13,7 @@ In the case where conflicting API client names would be migrated, the command wi
| `--lock-directory \| --ld` | No | ./output/pythonClient/ | Relative path to the directory containing the `kiota-lock.json` file. If not specified, all `kiota-lock.json` files within in the current directory tree will be used. | Yes, without its value |
| `--client-name \| --cn` | No | graphDelegated | Used with `--lock-directory`, it would allow to specify a name for the API client. Else, name is auto-generated as a concatenation of the `language` and `clientClassName`. | Yes, without its value |

## Using `kiota config migrate`
## Using `kiota workspace migrate`

Assuming the following folder structure:
```bash
Expand All @@ -31,10 +31,10 @@ Assuming the following folder structure:
```

```bash
kiota config migrate
kiota workspace migrate
```

_The resulting `kiota-config.json` file will look like this:_
_The resulting `workspace.json` file will look like this:_

```jsonc
{
Expand Down Expand Up @@ -112,10 +112,10 @@ _The resulting file structure will look like this:_
└─... # Generated code files
└─graph_client.py
└─apimanifest.json
└─kiota-config.json
└─workspace.json
```

## Using `kiota config migrate` for a specific `kiota-lock.json` file and a specific client name
## Using `kiota workspace migrate` for a specific `kiota-lock.json` file and a specific client name

Assuming the following folder structure:
```bash
Expand All @@ -133,10 +133,10 @@ Assuming the following folder structure:
```

```bash
kiota config migrate --lock-directory ./generated/graph/csharp --client-name GraphClient
kiota workspace migrate --lock-directory ./generated/graph/csharp --client-name GraphClient
```

_The resulting `kiota-config.json` file will look like this:_
_The resulting `workspace.json` file will look like this:_

```jsonc
{
Expand Down Expand Up @@ -176,5 +176,5 @@ _The resulting `kiota-config.json` file will look like this:_
└─graph_client.py
└─kiota-lock.json
└─apimanifest.json
└─kiota-config.json
└─workspace.json
```
12 changes: 6 additions & 6 deletions specs/scenarios/kiota-workspace.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Kiota Config
# Kiota Workspace

Kiota generates client code for an API and stores parameters in a kiota-lock.json file. A project can contain multiple API clients, but they are independently managed. Kiota has no awareness that an app has a dependency on multiple APIs, even though that is a core use case.

Expand All @@ -12,11 +12,11 @@ We have previously described Kiota's approach to managing API dependencies as co

## Proposal

We should introduce a new Kiota.config file that holds the input parameters required to generate the API Client code. Currently kiota-lock.json is used to capture what the parameters were at the time of generation and can be used to regenerate based on the parameters in the file. This creates a mixture of purposes for the file.
We should introduce a new Kiota workspace file that holds the input parameters required to generate the API Client code. Currently kiota-lock.json is used to capture what the parameters were at the time of generation and can be used to regenerate based on the parameters in the file. This creates a mixture of purposes for the file.

We did consider creating one kiota-config.json file as a peer of the language project file, however, for someone who wants to generate multiple clients for an API in different languages, this would be a bit annoying. An alternative would be to allow the kiota-config.json file to move further up the folder structure and support generation in multiple languages from a single file. This is more consistent with what [TypeSpec](https://aka.ms/typespec) are doing and would be helpful for generating CLI and docs as well as a library.
We did consider creating one workspace.json file as a peer of the language project file, however, for someone who wants to generate multiple clients for an API in different languages, this would be a bit annoying. An alternative would be to allow the workspace.json file to move further up the folder structure and support generation in multiple languages from a single file. This is more consistent with what [TypeSpec](https://aka.ms/typespec) are doing and would be helpful for generating CLI and docs as well as a library.

Here is an example of what the kiota-config.json file could look like.
Here is an example of what the workspace.json file could look like.

```jsonc
{
Expand Down Expand Up @@ -53,7 +53,7 @@ The [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.

## Commands

* [kiota config init](../cli/config-init.md)
* [kiota workspace init](../cli/workspace-init.md)
* [kiota client add](../cli/client-add.md)
* [kiota client edit](../cli/client-edit.md)
* [kiota client generate](../cli/client-generate.md)
Expand All @@ -64,7 +64,7 @@ The [API Manifest](https://www.ietf.org/archive/id/draft-miller-api-manifest-01.
### Migrate a project that uses Kiota v1.x for API client

```bash
kiota config migrate
kiota workspace migrate
```

### Get started to generate an API client
Expand Down

0 comments on commit 5eb2627

Please sign in to comment.