Working with workspaces

[samcragg]

I've just tried out some of the experimental workflow commands (introduced in #3356) and the flow wasn't quite what I was expecting so thought I'd start a discussion if that's okay, as it's such a great feature that would help me as a developer.

For background, although my strengths are back end C# code, I do work with a React front end project daily for work. Therefore, my initial mental model for how the workspace feature would work was along the lines of npm style tool where you initialise it and then modify the generated config file.

However, when adding a client to the workspace it also generates it. This forces the need to use the multitude of command line options for each setting. It also means there's an edit command for changing these settings.

Is there any desire to move away from the command line options and use the config file instead for these customisations, only having the bare minimum on the command line? Calling client add would still need the name and language, but it could create the config with all the defaults for that client. Once the developer has tweaked the file they would have to explicitly call generate (which already exists) to create the client.

The reason for this is discoverability; it's a lot easier to see all the options and their defaults in the file than having to read the docs.

It would also make it easier to add more customisation to the tool (I can't quite use it yet due to it not supporting required from the Open API spec and one of the reasons against adding that option was it would increase the complexity of the command line).

Just thought I'd raise it now, as these are new options so would be great to have the discussion now before they're released.

[baywet]

Hi @samcragg
Thank you for giving a try to this new experience and providing feedback!
CC @maisarissi @sebastienlevert

yes, you are correct, the workspace experience was modeled after npm and other similar package management experiences. There's more complexity to it though in terms of parameters.
This is why we introduced the edit command, so users do not have to re-specify all parameters every-time when they make changes.

This is also why the add command generates by default. When using the npm install command with a package name, you expect it to install the package right away, not to have to run a separate install command after. Have you seen the --skip-generation argument though? This helps you add all the clients you need without generating and then run the kiota client generate to generate them all at once.
 
The only required parameters for the add command should be the language, name, and source description, let us know if this isn't the case?

The philosophy of the CLI experience is that you should be able to do everything you can do through the configuration files or any UI, through the command line. We're not planning on making the CLI a subpar experience.

Let's park the discussion around required things in OAS in #3911

Let us know if you have further questions/concerns.

[samcragg]

Thanks for the reply and for correctly pointing out that npm install does the install too (similar to dotnet add, which restores too but has the option option not to). That makes sense. I'd still question the need for the edit command though - once you've called add won't you have a json file that you can edit?

Unfortunately, I'm struggling to try the command out even with the --skip-generation option as I get an error:

crit: Kiota.Builder.KiotaBuilder[0]
      error adding the client: The baseUrl must be a valid URL and end in a slash. (Parameter 'ApiDeploymentBaseUrl')

The OpenAPI json file I'm pointing to does work with the normal generate command, so it looks like there's not a feature parity with the new client command just yet but I'll have a look at the cause as don't want to sidetrack the discussion.

[baywet]

Thanks for the additional information.
Can you create an issue for the baseUrl thing, we'll need to look into it, but I believe it shouldn't require this if you have --skip-generation.

The reasoning behind the edit command is because we don't want people to have to open an editor, etc, they should be able to do everything from the CLI, that's a design principle we have in kiota. Of course you can simply edit the file and call the client generate command as well.

The inner generation logic is exactly the same for the "older" commands and the newer ones, I'm surprised you're getting a difference in experience between the two for the same exact description. Please share your findings once you have more information.

[baywet]

Just as an update to anyone else who might be reading this. This message came from an outdated dependency which has been upgraded #5227 (available with the latest preview release from yesterday)