Microsoft.OpenApi.Kiota.ApiDescription.Client

[kimbell]

Why has Microsoft.OpenApi.Kiota.ApiDescription.Client been abandoned? It's unlisted from Nuget. We currently use this infrastructure with NSwag and are looking into using Kiota.

Today we can just update the json file, and everything happens automatically.
With Kiota, we would have to update the file, then run the kiota tool.

Since this is relatively new infrastructure from Microsoft, an explanation for your decision in the docs would be helpful.

[baywet]

Thanks for your interest in kiota and for reaching out. There are multiple reasons why we deprecated this package:

• extremely low usage (264 overall downloads at the time of writing, and the vast majority of those is probably from Microsoft)
• to provide a complete experience, visual studio would have needed to install kiota, and to update the "add open api reference" experience. Which was not prioritized by the Visual Studio team.
• we shipped a Visual Studio Code extension which offers a much better experience. (and we're considering extensions to other IDEs like JetBrain intelliJ or VS)

To be clear, this decision has no impact on the NSwag experience itself and was only related to the Kiota integration with the "add an OpenAPI reference" experience.

Additionally @christianhelle integrated Kiota in REST client code generator, you should give it a try. ( Christian, maybe you should PR the docs similarly to what Andrea has done MicrosoftDocs/openapi-docs#4)

Don't hesitate to provide more feedback and context about your scenario if you feel we're still missing something at this point.

[christianhelle]

Additionally @christianhelle integrated Kiota in REST client code generator, you should give it a try. ( Christian, maybe you should PR the docs similarly to what Andrea has done MicrosoftDocs/openapi-docs#4)

I did think about that a couple of times but it felt a bit too pushy to promote my tools via the official MS documentation channels. But since @baywet mentioned it then I would really love to link to my tools and provide usage instructions as well

[baywet]

@christianhelle it only feels fair to promote your work :) Just make sure you base your PR off Andrea's one please.

[kimbell]

I have trouble seeing how Visual Studio comes into play. If something requires an IDE specific feature, it's a big red flag. Over the last 20 years I've been through enough crap that was bound to VS that didn't get updated as newer versions became available.

The way NSwag is set up isn't very complicated, and something Kiota also should be able to mirror. NSwag provides a nuget package NSwag.ApiDescription.Client that contains the console application used to generate code. This package also contains some MSBuild magic that enables it to hook into the ApiDescription.Client infrastructure.

The generated code contains tons of references to Newtonsoft, but doesn't install Newtonsoft. The assumption is that the package already has been installed. If your system requires some packages to be present before running the tool, document it.

Currently you expect users to call a command line tool to generate code. I'm guessing most people will add some custom MSBuild to call this automatically. If you provided the MSBuild glue, it would give developers another option if they wanted to use it and it fits into what other Microsoft Teams are doing. I'm guessing they didn't do it if nobody wanted it.

You are quoting a low usage count as reason for cutting this; a package with 2 msbuild files and a nuspec. Since the package has been unlisted, no new consumers will find it. The latest version I can find is 0.5.0-preview2 and based on other packages still available, I'm guessing that makes it around September 2022. Version 1 of your tooling was released March 2023. I wouldn't even know about Kiota unless a colleague had heard something at a conference. I can't remember seeing anything related to Kiota in any of the channels I follow.

I had a look at the Rest Client Generator that you mentioned. Visual Studio 2022 isn't listed as a supported version.
When I see dependencies as NPM and JAVA, then it becomes a showstopper for me. It will really need some stellar functionality for me to voluntarily suffer through NPM hell.

When I clone a .NET project and build it, I just want it to work. I'm already there now with NSwag, but System.Text.Json support is experimental. I was hoping Kiota could be an alternative. So far I've only done basic Kiota testing, so I have no idea if more advanced scenarios such as polymorphism works; supported by System.Text.Json in .NET7. When the initial setup is a step back from what I already have, doesn't encourage me for further exploration.

[christianhelle]

@kimbell There is a separate VSIX package for REST API Client Code Generator for VS 2022

[christianhelle]

@kimbell NPM and Java are only required for using AutoRest, Swagger Codegen, and OpenAPI Generator.

NSwag, Kiota, and Refit code generators don't require anything else than Visual Studio