My team evaluated adopting kiota and we found the ergonomics to be really poor and the generated libraries to be needlessly over complicated and difficult to use.
We evaluated c# and typescript.
Which sucks, because the alternatives aren’t much better. Maybe I’m missing something but the swagger/openapi client generators shouldn’t be this bad as a rule…
I tried for Typescript and was likewise surprised when I opened the code; it leveraged a lot of dynamic features that felt unnecessary in code that was already templated.
I think the code might be the result of dealing with highly variadic endpoints (e.g accepts either JSON or XML, and accepts either basic auth or OAuth, and produces one of 4 different response objects), combined with trying to minimize the bundle size for browsers. The code looks extremely lean; I wouldn't be surprised if more explicit code was 10x the size.
That doesn't really explain the C# code; I'm not a C# dev, but I wouldn't expect "lines of code" to directly impact performance the way it does for browsers.
one of the main advantages of kiota is that is doesn't assume anything about the API you're consuming, contrary to other generators. This means it'll need to carry more information like the media types etc... in the generated code as opposed to dependencies.
And yes! one reason why TypeScript is not yet "stable" when compared with other languages is because we've spent a great deal of time optimizing for size. One of the many optimizations was to use interfaces over classes whenever possible, and when not, use proxies over actual classes. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...
This is why for a small set of operations (<100) the added weight of a TypeScript client at runtime is almost negligeable.
For dotnet size matters as well, especially when you consider scenarios like embedded or front end development or large APIs. Similarly, we've spent time optimizing for runtime size.
we are using the nswag tolchain (https://github.com/RicoSuter/NSwag) for generating c# and typescript clients based on openapi specs generated by swashbuckle. you can tweak some details using config file too.
it works quite well and even has integration in msbuild to avoid manual cli steps.
It is an unfortunate situation. I have this side project sketch since a year ago or so to implement a new gRPC-tooling-like OpenAPI generator for .NET, but sadly haven't had enough time for this kind of project as of lately.
We could have had so much better UX, there really is no reason to have it as bad...
Yeah, now I'm just writing openapi yamls by hand and separately I write necessary code. Generators are so bad that I'm not going to use them. May be I should just write my own generator, but so far it seems like unnecessary complication.
For .NET, it produces "recommended" boilerplate, specifically serialization that uses correctly configured System.Text.Json in source generated mode. This makes it usable in AOT workloads and there have been fixes by Filip Navara to significantly reduce binary size impact.
For other languages, I suppose it's an organizational effort within MS to standardize and consolidate SDK generation to produce consistent experience.
More on .NET, last time I compared OpenAPI generator options - other generators did not do this or did it in a worse way.
Even still, I do not consider Kiota to have the kind of UX that .NET deserves.
For example, to consume gRPC-based API, your workflow is just:
That's it - the client is generated transiently and is a part of the project without getting in your way, I have a small shell script to do it as a one-liner. And maintaining a dependency of an application on a remote API of this kind is also easy if .proto is available via git - add it as a submodule or a subtree and just bump commits automatically (or manually if review is needed).
You never need to manually re-generate and possibly re-reference or re-publish a separate client package for this to work. The sheer convenience of this at both individual and organizational level alone makes a compelling case for choosing gRPC over REST, architectural preferences notwithstanding.
Last time I checked, Kiota required much more effort and ceremony. I understand that it's a "big generator to rule them all" that made to address both simple one-off APIs and ginormous Azure SDK, but .NET has all necessary building blocks to have similar or even better UX to what gRPC tooling provides. I suppose, it's just a matter of doing it and promoting the project.
No Azure SDK is generated with Kiota today. Some use Autorest, some are handcrafted. This is mostly because kiota came out after all those SDKs, partly because Autorest assumes REST API conventions from the Azure design guidelines https://azure.github.io/azure-sdk/dotnet_introduction.html
The only set of public SDKs generated by kiota from Microsoft are the Microsoft Graph SDKs.
I've ran a few tests with Kiota and I found that the generated code is awkward and needlessly hard to integrate. It's good to have options available but with openapi-generator around I hardly see the point of bothering with Kiota.
Being different does not imply being better or worst. Again, any specify example on how the generated code could be better? (e.g. nullability information, etc...)
Kiota allows you to select the operations/APIs you care about for your client application instead of generating the whole API surface. That makes for a more nimble client.
I just updated our Swagger generators to the latest version of swagger-codegen.
It doesn't immediately look like kiota can be extended in the same way swagger-codegen-cli can with custom generators, which is a shame. Definitely a nice feature.
My team evaluated adopting kiota and we found the ergonomics to be really poor and the generated libraries to be needlessly over complicated and difficult to use.
We evaluated c# and typescript.
Which sucks, because the alternatives aren’t much better. Maybe I’m missing something but the swagger/openapi client generators shouldn’t be this bad as a rule…
I tried for Typescript and was likewise surprised when I opened the code; it leveraged a lot of dynamic features that felt unnecessary in code that was already templated.
I think the code might be the result of dealing with highly variadic endpoints (e.g accepts either JSON or XML, and accepts either basic auth or OAuth, and produces one of 4 different response objects), combined with trying to minimize the bundle size for browsers. The code looks extremely lean; I wouldn't be surprised if more explicit code was 10x the size.
That doesn't really explain the C# code; I'm not a C# dev, but I wouldn't expect "lines of code" to directly impact performance the way it does for browsers.
one of the main advantages of kiota is that is doesn't assume anything about the API you're consuming, contrary to other generators. This means it'll need to carry more information like the media types etc... in the generated code as opposed to dependencies.
And yes! one reason why TypeScript is not yet "stable" when compared with other languages is because we've spent a great deal of time optimizing for size. One of the many optimizations was to use interfaces over classes whenever possible, and when not, use proxies over actual classes. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...
This is why for a small set of operations (<100) the added weight of a TypeScript client at runtime is almost negligeable.
For dotnet size matters as well, especially when you consider scenarios like embedded or front end development or large APIs. Similarly, we've spent time optimizing for runtime size.
we are using the nswag tolchain (https://github.com/RicoSuter/NSwag) for generating c# and typescript clients based on openapi specs generated by swashbuckle. you can tweak some details using config file too. it works quite well and even has integration in msbuild to avoid manual cli steps.
It is an unfortunate situation. I have this side project sketch since a year ago or so to implement a new gRPC-tooling-like OpenAPI generator for .NET, but sadly haven't had enough time for this kind of project as of lately.
We could have had so much better UX, there really is no reason to have it as bad...
Yeah, now I'm just writing openapi yamls by hand and separately I write necessary code. Generators are so bad that I'm not going to use them. May be I should just write my own generator, but so far it seems like unnecessary complication.
The openapi yaml can be generated (in dotnet) by swashbuckle.
I hand roll the http client libraries, too
What does this offer that openapi-generator and swagger-codegen don't already do?
For .NET, it produces "recommended" boilerplate, specifically serialization that uses correctly configured System.Text.Json in source generated mode. This makes it usable in AOT workloads and there have been fixes by Filip Navara to significantly reduce binary size impact.
For other languages, I suppose it's an organizational effort within MS to standardize and consolidate SDK generation to produce consistent experience.
More on .NET, last time I compared OpenAPI generator options - other generators did not do this or did it in a worse way.
Even still, I do not consider Kiota to have the kind of UX that .NET deserves.
For example, to consume gRPC-based API, your workflow is just:
That's it - the client is generated transiently and is a part of the project without getting in your way, I have a small shell script to do it as a one-liner. And maintaining a dependency of an application on a remote API of this kind is also easy if .proto is available via git - add it as a submodule or a subtree and just bump commits automatically (or manually if review is needed).You never need to manually re-generate and possibly re-reference or re-publish a separate client package for this to work. The sheer convenience of this at both individual and organizational level alone makes a compelling case for choosing gRPC over REST, architectural preferences notwithstanding.
Last time I checked, Kiota required much more effort and ceremony. I understand that it's a "big generator to rule them all" that made to address both simple one-off APIs and ginormous Azure SDK, but .NET has all necessary building blocks to have similar or even better UX to what gRPC tooling provides. I suppose, it's just a matter of doing it and promoting the project.
The azure SDK is terrible, mostly due to Kiota…
No Azure SDK is generated with Kiota today. Some use Autorest, some are handcrafted. This is mostly because kiota came out after all those SDKs, partly because Autorest assumes REST API conventions from the Azure design guidelines https://azure.github.io/azure-sdk/dotnet_introduction.html
The only set of public SDKs generated by kiota from Microsoft are the Microsoft Graph SDKs.
I've ran a few tests with Kiota and I found that the generated code is awkward and needlessly hard to integrate. It's good to have options available but with openapi-generator around I hardly see the point of bothering with Kiota.
do you have specific examples of what lead you to this conclusion?
> do you have specific examples of what lead you to this conclusion?
Just get a spec, run kiota,and check the output.
Compare with the output from, say, openapi generator.
No one can miss the difference.
Being different does not imply being better or worst. Again, any specify example on how the generated code could be better? (e.g. nullability information, etc...)
Probably nothing except being an official microsoft backed project.
Kiota allows you to select the operations/APIs you care about for your client application instead of generating the whole API surface. That makes for a more nimble client.
Who’s optimizing for the size of their http client and using AI code generators?
If you don't use MS stack, nothing really.
I always thought that generated code is generally considered a bad idea, but generating types on the other hand is a bit more feasible.
So I wrote a small utility to generate typescript types based on openapi files, so that they can be applied to an axios client.
No code, just types. Quite out of date now though.
https://github.com/ivank/laminar/tree/main/packages/cli#axio...
I just updated our Swagger generators to the latest version of swagger-codegen.
It doesn't immediately look like kiota can be extended in the same way swagger-codegen-cli can with custom generators, which is a shame. Definitely a nice feature.
Will this work on a .net 4.7 project?
Yes! According to the documentation it supports netfx 4.6 or net6 and up. https://learn.microsoft.com/en-us/openapi/kiota/quickstarts/...
There's older versions of Autorest for that. But you could encounter issues between swagger V2 and V3, since V3 is newer
Surprised to see php code from Microsoft
Like many large companies, Microsoft uses PHP internally. From word of mouth I believe it drives some services in their cloud platform.
Nice to hear.
Wonder how this compares to Autorest which is another MS project that does the same thing.