Kiota: OpenAPI-based HTTP client code generator(github.com)
github.com
Kiota: OpenAPI-based HTTP client code generator
https://github.com/microsoft/kiota
29 comments
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.
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.
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...
We could have had so much better UX, there really is no reason to have it as bad...
[deleted]
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
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:
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.
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:
dotnet add package Grpc.Tools
dotnet add package Grpc.Net.Client
dotnet add package Google.Protobuf
# add <Protobuf Include="myapi.proto" /> to .csproj
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.
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.
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.
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...
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.
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
Wonder how this compares to Autorest which is another MS project that does the same thing.
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…