How to create OpenAPI-server and openapi.yaml for Kiota?

[guettli]

I know that Kiota creates OpenAPI clients.

Just our of curiosity: How do you write the corresponding openapi server?

I want to write an openapi server in Go.

I guess there are two ways:

way-1: write the yaml and somehow create server-stubs from the yaml

way-2: write Go code and somehow create the openapi.yaml.

How would you do this?

[baywet]

Hey @guettli,
Both ways are "correct" it only depends on your process.

• The design first approach (YAML) focuses on specifying ahead of time the API shape and behaviour to later build the best experience possible for the client and make sure the API honours the contract.
• The code first approach focuses on rapid iterations and projecting tooling to clients as fast as possible, sometimes at the expanse of the client experience.

It really comes down to answering questions like:

• How big is your team?
• Do you have company API guidelines?
• Do you have a formal API review process?
• How many clients is this API anticipated to be exposed to?
• Is that API going to be public? (discovery experience)
• ....

In asp.net world (I don't have experience building APIs in Go) both approaches exist:

• People write their OpenAPI description and then either handcraft or code-gen the API controllers.
• People write controllers first, and use OpenAPI.net and the web extensions to generate the API description.

I know this sounds like a consultant "it depends" type of answer, but it really depends, mostly on your organization and what problems the API you're building is going to solve.

[guettli]

Yes, it depends. I think it depends a lot on "which tooling is more mature". Kiota looks good, but I could not find a sane default for the server.

[baywet]

We've been asked a couple of times to get into generating the service side as well by internal teams. This is something we've declined so far to stay focused and provide provide the best client side experience we could. Once kiota GAs, and the languages support stabilizes and if we see demand for it, this is something we might re-consider. But the decision point for that is probably at least a year from now and then we'll need time to implement that aspect.

[guettli]

Thank you for your answer.

[fdcastel]

Hi! Just checking in to see if there have been any advancements in this area over the past two years?

Is the development of C# code for server APIs currently in the radar? (controllers, Minimal API, or any other?)

[baywet]

Thank you for using kiota and for reaching out.
No progress has been made on that front since the last answer.
The main reason being the demand is low (when compared to client generation) and we've had to focus on AI manifest generation for the past semester (in addition to ongoing investments on the client generation)
Let us know if you have any additional comments or questions.

[fdcastel]

Thank you @baywet for the quick and informative reply. I can fully understand.

Keep up the fantastic Work!

[visschersm]

I just learned about kiota and was wondering the same.
Would like to see a proper way to generate my server side contracts as well using the same tool to prevent having to use a bunch of tools all with there own pros and cons.
Currently mostly working with nswag (dotnet), which goes both ways, but have seen openapi-generator being used as well.
imo it would be nice to centralize the API specification and generate both ways so that the contract is leading.

But for now i'll just study kiota a bit to see how to generate some nice client applications.